|
Персональные инструменты |
![]() |
||
|
![]() |
![]() SGML DocbookМатериал из CustisWikiВерсия от 18:03, 4 сентября 2008; StasFomin (обсуждение | вклад) (→Вопросы и ответы: обновление данных) DocBook — приложение SGML или XML (проще говоря — популярный набор тэгов), предназначенное для разметки документов, такое же, как HTML для разметки веб-документов. Но в отличие от HTML, Docbook не предоставляет информацию о визуальном представлении документа. Преобразованием Docbook документа в форматы, доступные для печатного или просто визуального представления занимаются различные утилиты, обычно осуществляющие такое преобразование на основе настраиваемых шаблонов, т. е. происходит настоящая изоляция структуры документа от визуального представления. СодержаниеИсторияDocbook был рожден в 1991 году (первоначально — для облегчения переноса troff-меченой UNIX-документации), и, в разное время, развивался и поддерживался различными организациями:
ПримерЗаголовокРассмотрим заголовок XML Docbook документа: <?xml version='1.0' encoding="windows-1251"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0/EN" "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" [ <!ENTITY nwalsh "Norman Walsh"> <!ENTITY chap1 SYSTEM "chap1.sgm"> <!ENTITY chap2 SYSTEM "chap2.sgm"> ]> Документ в формате SGML Docbook будет абсолютно такой же, только без первой строчки (XML-декларации). Вообще XML—версия Docbook более строгая, но более легкая в понимании и изучении. (XML проще чем SGML, но не такой мощный). Так как XML также является SGML—приложением, все программые средства SGML могут быть использованы. Основное различие между SGML и XML версиями состоит в следующем (применимо для всех XML — приложений):
<B><A HREF="some_url">click here</B></A> вы должны использовать правильную вложенность: <B><A HREF="some_url">click here</A></B>. Итак, заголовок состоит из
КомментарииКомментарии оформляются стандартно для SGML синтаксиса (и следовательно XML-синтаксиса), и встречаться где угодно, после декларации и внутреннего подмножества, (исключая содержимое литералов и блоков сырых данных): <!--Комментарии оформляются стандартно для [[SGML]] синтаксиса --> <title>Приложение глазами пользователя</title> &lib-app-struct.sgm; <!-- Структура приложения --> &lib-app-interface-forms.sgm; <!-- Экранные формы --> &lib-app-interface-usage.sgm; <!-- Способы работы с областями формы --> &lib-app-interface-database.sgm; <!-- Особенности работы с базой данных --> Корневой элементЗа заголовком (если не рассматривать возможные комментарии) должен идти корневой элемент, «book» или «set». Идентификаторы, публичные и системные, каталог-файлыСсылку из документа на DTD или другой внешний файл можно оформить
В XML-версии, обязательно предоставлять системный идентификатор (даже если есть публичный).
' ( ) + , - . / : = ? а также пробелы и переводы строки. Главное — они должны быть глобально уникальными. Поэтому, принято использовать формальные публичные идентификаторы (Formal public identifiers, FPI), предложенные стандартом ISO 8879, правило формирования которых должно обеспечивать их уникальность: prefix//owner-identifier// text-class text-description// language//display-version где:
Примеры: +//ISO/IEC 9070/RA::A00002//... +//IDN oreilly.com//... -//OASIS//... -//Davenport//... -//IDN custis.ru//...
-//ISO 8879-1986//ENTITIES Added Latin 1//EN
-//ISO 8879-1986//ENTITIES Added Latin 1//EN//XML Отображение с публичных идентификаторов (включая формальные) на системные идентификаторы, должно происходить посредством каталог-файлов. Стандарт на SGML-catalog файлы находится здесь — OASIS Technical Resolution 9401:1997, а стандарт «XML Catalog» пока еще не готов. Файловая (физическая) структура документаДокумент можно легко разделить на несколько файлов, с использованием объектов-подстановок (entities) следующим очевидным образом: <!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ <!ENTITY intro.sgm SYSTEM "intro.sgm"> <!ENTITY sgml.sgm SYSTEM "sgml.sgm"> <!ENTITY db.sgm SYSTEM "db.sgm"> <!ENTITY lib-sql.sgm SYSTEM "lib-sql.sgm"> <!ENTITY lib-tools.sgm SYSTEM "lib-tools.sgm"> ]> <book id="lib-book-tech" lang="ru"><title>Технологии разработки</title> &intro.sgm; <!-- О документе --> &sgml.sgm; <!-- Ведение документации --> &db.sgm; <!-- Описание информационной модели --> &lib-sql.sgm; <!-- Разработка серверной части --> &lib-tools.sgm; <!-- Дополнительные средства --> </book> Обратите внимание, что включаемые файлы, содержащие части документа, не должны содержать никаких заголовков или деклараций — файл intro.sgm: <preface ID="intro" revision="$Date: 2001/12/27 14:25:13 $"> <title>Структура документа</title> <abstract><para>Данная книга содержит информацию о применяемых технологиях разработки проектов и предназначена для использования в качестве справочника по ним.</para> </abstract> </preface> Можно отделить и автоматизировать процесс декларации Docbook-файлов в виде entities, например написав скрипт, который для всего каталога генерирует файл !filelist (рекурсивно включающий файлы !filelist из подкаталогов): <!ENTITY % subdirectory1.fl SYSTEM "subdirectory1\!file-list"> %subdirectory1.fl; <!ENTITY % subdirectory2.fl SYSTEM "subdirectory2\!file-list"> %subdirectory2.fl; <!ENTITY intro.sgm SYSTEM "intro.sgm"> <!ENTITY sgml.sgm SYSTEM "sgml.sgm"> <!ENTITY db.sgm SYSTEM "db.sgm"> <!ENTITY lib-sql.sgm SYSTEM "lib-sql.sgm"> <!ENTITY lib-tools.sgm SYSTEM "lib-tools.sgm"> Сам документ при этом становиться неизменным, и в нем, с помощью entities можно включать все файлы из каталога документа и его подкаталогов: <!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ <!ENTITY % file-list SYSTEM "!file-list"> %file-list; ]> <book id="lib-book-tech" lang="ru"><title>Технологии разработки</title> &intro.sgm; <!-- О документе --> &sgml.sgm; <!-- Ведение документации --> &db.sgm; <!-- Описание информационной модели --> &lib-sql.sgm; <!-- Разработка серверной части --> &lib-tools.sgm; <!-- Дополнительные средства --> </book> Логическая структура документаЭлементы Docbook можно разделить на
Вложенность структурных элементов удобно наблюдать на следующей (гипертекстовой) диаграмме: setСамый верхний элемент docbook. Он может включать две или более связанных book, которые могут содержать ссылки («xref», «link») друг на друга (например, комплект документации по программному продукту, включающему «техническое задание», «руководство пользователя», «руководство системного администратора» и «руководство программиста»). book«Книга» — наиболее распространенный корневой элемент. partРаздел уровня выше чем глава. referenceСправочник, т. е. набор справочных статей (вида «Unix Man» статей). articleСтатья общего вида (конкретный тип статьи специфицируется с помощью атрибутов).
chapterГлава (верхнего уровня). Обязательно должен быть между «book» и «section». sectionРаздел. Разделы можно неограничено и гибко вкладывать друг в друга с помощью «section», либо использовать вложение элементов-разделов фиксированных уровней: sect1 / sect2 / sect3 / sect4 / sect5 simplesectТерминальный (листовой) раздел. Раздел этого уровня не должен попадать в «Содержание» (Table of Contents). Блочные элементыБлочные элементы находяться ниже уровня структурных элементов, по сути, это элементы уровня параграфов: списки, замечания, синопсисы, таблицы, рисунки и т. п. Списки
<programlisting> print "hello world" <co id="co1-op1"> call do_work("yes") <co id="co1-op2"> return 1 <co id="co1-op3"> <calloutlist> <callout arearefs="co1-op1"><para>Оператор print, выводит строку на консоль</para></callout> <callout arearefs="co1-op2"><para>Пример вызова функции.</para></callout> <callout arearefs="co1-op3"><para>Дальше могут идти другие операторы.</para></callout> </calloutlist> </programlisting>
<glossdiv> <glossentry> <glossterm id="db--association">ассоциированный объект</glossterm> <glossdef><para>Объекты которые каким-либо образом связаны с другим объектом, который в данный момент рассматривается как текущий. Например: <quote>все неоплаченные требования к контрагентам данного менеджера</quote>. </para></glossdef> </glossentry> </glossdiv>
Процедура может работать в следующих режимах (значение параметра <literal>a_regim</literal>). <itemizedlist mark="bullet" spacing="compact"> <listitem><para><systemitem>do</systemitem>; </para></listitem> <listitem><para><systemitem>undo</systemitem>; </para></listitem> <listitem><para><systemitem>redo</systemitem>. </para></listitem> </itemizedlist>
Могут быть разные причины того, что подсистема не предоставляет доступа к системе: <orderedlist> <listitem><para>неверно указан адрес страницы internet, в результате чего фактически выполняется обращение к другой, также закрытой странице;</para></listitem> <listitem><para>ошибка (опечатка) во введенном пароле - необходимо еще раз внимательно ввести пароль;</para></listitem> <listitem><para>ошибка во введенном пароле может заключаться в том, что пользователь не переключил шрифт с русского на латинский или наоборот, а также режим ввода больших букв - необходимо проверить режим работы клавиатуры. </para></listitem> </orderedlist>
<segmentedlist> <segtitle>Разработчик</segtitle> <segtitle>Платформа</segtitle> <segtitle>Язык</segtitle> <seglistitem> <seg>Macrosoft</seg> <seg>Win32</seg> <seg>C++</seg> </seglistitem> <seglistitem> <seg>ЗИС</seg> <seg>Linux</seg> <seg>Python</seg> </seglistitem> </segmentedlist>
<emphasis role="bold">Методы наследованные от java.lang.Object</emphasis>: <simplelist type="inline"> <member><literal>hashCode</literal></member> <member><literal>finalize</literal></member> <member><literal>notify</literal></member> <member><literal>notifyAll</literal></member> <member><literal>registerNatives</literal></member> <member><literal>wait</literal></member> <member><literal>getClass</literal></member> <member><literal>clone</literal></member> <member><literal>equals</literal></member> <member><literal>toString</literal></member> </simplelist>
<variablelist><title>Входы пакета pk_name</title> <varlistentry> <term>name_short(a_name)</term> <listitem><para>Принимает необработанное название и возвращает его <systemitem>краткую форму нормализованного названия</systemitem>. </para></listitem> </varlistentry> <varlistentry> <term>name_trans(a_name)</term> <listitem><para>Принимает <systemitem>полную форму нормализованного названия</systemitem> и возвращает <systemitem>краткую форму нормализованного названия</systemitem>. </para></listitem> </varlistentry> <varlistentry> <term>name_full(a_name)</term> <listitem><para>Принимает необработанное название и возвращает его <systemitem>полную форму нормализованного названия</systemitem>. </para></listitem> </varlistentry> </variablelist> ЗамечанияНа самом деле, семантика разного типа заметок не сильно определена, и в основном, выбор типа заметки определяется или корпоративными правилами, или ожидаемым форматированием (например, разные типы заметок могут форматироваться блоками с разными графическими значками-предупреждениями).
<сaution><para>Наверняка есть другие источники информации, а также другая поступающая информация. Так что этот список нуждается в расширении и доработке. </para></сaution>
<important><para>При загрузке все нулевые значения отрезаются и не вводятся!</para></important>
<note><para>Этот размер различен для различных операционных систем и определяется для каждой из них отдельно. </para></note>
<tip><para>Каждый вопрос имеет ответ по умолчанию, который принимается при нажатии кнопки <interface>Enter</interface>.</para></tip>
<warning><para><emphasis>Нельзя</emphasis> получать новые версии файлов другим путем, кроме как выполнением команд <systemitem>update</systemitem> или <systemitem>checkout</systemitem>. Копирование новых версий файлов с другого компьютера может привести к потере данных! </para></warning> Специальные блоки
<programlisting> delete from tsum_sub s1 -- нулевые суммы там, где нет ненулевых where s1.s_money = 0 and not exists (select 1 from tsum_sub s2 where s2.cod_pl = s1.cod_pl and s2.cod_u = s1.cod_u and s2.s_money ≠ 0 ); </programlisting>
<synopsis> cvs add -kb <replaceable>имя файла</replaceable> </synopsis> Таблицы, рисунки, примерыВерсии элемента с префиксом «informal», означают отсутствия вложенного элемента «title» (заголовка).
<example id="exmp-xforms-request"><title>Пример XForms-спецификации</title> <programlisting width="80"><![CDATA[<?xml version="1.0" encoding="windows-1251"?> <xform:xform> <xform:input ref="accNumber"> <xform:caption>Учетный номер</xform:caption> </xform:input> <xform:input ref="releaseDate"> <xform:caption>Дата выпуска</xform:caption> </xform:input> ... </xform:xform> ]]></programlisting> </example>
<figure id="lib-cis-structure-pict"> <title>Структура компонентов cis-forms</title> <graphic entityref="interface-structure.gif " align=center scale=100></graphic> </figure> <table frame="all"> <title>Автопрепроцессирование</title> <tgroup cols="5" align="left"> <colspec colnum="1" colname=c1 colwidth=4cm > <colspec colnum="2" colname=c2 colwidth=4cm> <thead> <row><entry>sgml-таг</entry><entry>html-таг</entry></row> </thead> <tbody> <row><entry>para </entry><entry>p align="justify" </entry></row> <row><entry>listitem </entry><entry>li </entry></row> <row><entry>listitem </entry><entry>li </entry></row> <row><entry>orderedlist </entry><entry>ol </entry></row> <row><entry>orderedlist </entry><entry>ol </entry></row> <row><entry>itemizedlist </entry><entry>ul </entry></row> <row><entry>itemizedlist </entry><entry>ul </entry></row> <row><entry>systemitem </entry><entry>em </entry></row> <row><entry>systemitem </entry><entry>em </entry></row> <row><entry>literal </entry><entry>code </entry></row> <row><entry>literal </entry><entry>code </entry></row> </tbody> </tgroup> </table> Параграфы
УравненияЕсть элементы «equation», «informalequation» и «inlineequation». Следует отметить, что в Docbook практически нет средств описания математических формул, но со временем можно ожидать поддержки MathML в XML-версии Docbook. <equation><title>Fermat's Last Theorem</title> <mathphrase>x<superscript>n</superscript> + y<superscript>n</superscript> ?z<superscript>n</superscript> ? n ? 2</mathphrase> </equation> Графика и другие медиафрагментыДля рисунков, которые вкладываются внутрь блочных окружений типа «figure» ранее использовался элемент «graphic», а для внутристрочных картинок (вероятно, небольших значков) — элемент «inlinegraphic» <para>Вызывается из пункта меню <literal>Правка/Добавить</literal>, или на панели инструментов кнопка <inlinegraphic entityref="insert.gif"></inlinegraphic> или клавиша <literal>shift+F4</literal>. Для вставки произвольных медиафрагментов в версии Docbook 5.0 нужно использовать использовать «mediaobject» и «inlinemediaobject». Вопросы и ответыРазличные коллекции ответов на вопросы (в частности, FAQ) можно сделать с помощью элемента «qandaset»(deprecated), состоящего из элементов «questions»(deprecated) и «answers»(deprecated). Остальные блочные элементы
<blockquote> <para>Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.</para> </blockquote>
<procedure><title>Алгоритм pkb_prim_control.create_procedure </title> <step><para>Проверяем SQL-запрос заданного формата на синтаксис.</para></step> <step><para>Формируем текст процедуры первичного контроля.</para></step> <step><para>Создаем процедуру с полученным текстом но с именем F_TEST_LOAD. </para></step> <step><para> Проверяем созданную процедуру на ошибки. </para></step> <step><para> Создаем настоящую процедуру с именем PRIM_LOAD_[название формата]. </para></step> <step><para> Выдаем на созданную процедуру грант схеме DIC на выполнение. </para></step> </procedure>
<sidebar> <para>Абзац может быть выделен рамкой.</para> </sidebar> Общие атрибутыНиже представлен список атрибутов, общих для всех (или большинства) элементов и их значения. ArchТекстовая строка, специфицирующая компьютерную архитектуру, к которой применим Docbook элемент. ConditionОбщеполезная текстовая строка. Ее можно использовать произвольно, для настройки хитрых корпоративных регламентов сборки документов. ConformanceТекстовая строка, означающая соответствие содержимого элемента каким-либо стандартам. IDНаиболее важный атрибут. Позволяет присвоить любому элементу уникальный (внутри документа) идентификатор, чтобы впоследствии ссылаться на него (элементами «xref», «link»). Должен начинаться с латинской буквы, содержать алфавитно-цифровые символы и «-». Вообще, содержимое должно удовлетворять требованиям к именам из SGML Declaration (например, длина идентификатора ограничена NAMELEN). LangДвухбуквенный код языка, по ISO 639. Дополнительно, после «-» можно использовать код страны (ISO 3166). Например, «ru», «ru-RU», «en-US». Может использоваться при формировании выходного документа для выбора правил переноса и форматирования параграфов. OSТекстовая строка, описывает операционную систему, к которой применим элемент и его содержимое. RemapRemap contains an element name or similar semantic identifier assigned to the content in a previous markup scheme. RoleТекстовая строка для классификации (или подклассификации) элемента. Домен значений различный у различных элементов. RevisionТекстовая строка, идентифицирующая ревизию (версию) содержимого элемента. Например, если исходные тексты находяться под управлением CVS, можно использовать revision="$Id" и тогда CVS сам подставит CVS-версию документа в значение атрибута. RevisionFlagДомен значений — (changed, added, deleted, off). Может использоваться для отслеживания изменения статуса документа, от одной версии к другой. SecurityТекстовая строка, определяющая уровень конфиденциальности элемента и его содержимого. UserLevelТекстовая строка, определяющая уровень компетентности пользователя, необходимый для понимания содержимого элемента. Например, так можно вести документы, содержащие в себе и обзорные части, направленные на обычных пользователей, и сложные технические разделы, предназначенные для экспертов. VendorТекстовая строка опредедяющая «computer vendor»-а, относящегося к данному элементу. XrefLabelТекстовая строка, содержащая текст, который должен быть использован при подстановке в ссылке («XRef»), сделанной на этот элемент. statusАтрибут содержит редакционный или издательский статус включаемого блока текста. Домен его значений не специфицирован, т. е. можно вводить произвольные значения. Например, использовать набор:
Cсылочные атрибутыlinkendВ нем указывается ID элемента, на который ссылаются. Обработка Docbook-документов
С помощью DocBook можно разметить несколько видов документов: заметки и книги и наборы книг. DocBook имеет две реализации — SGML и XML. XML — версия более строгая, но более легкая в понимании и изучении. Так как XML также является SGML — приложением, все программые средства SGML могут быть использованы. Основное различие между SGML и XML версиями состоит в следующем (применимо для всех XML — приложений:
<B><A HREF="some_url">click here</B></A> вы должны использовать правильную вложенность: <B><A HREF="some_url">click here</A></B>. Приведем пример документа в SGML Docbook формате: <Section ID="lib-m4-ref" status="Черновик" role="" revision="$Date: 2000/08/30 11:49:05 $"> <title>Справочник по препроцессору m4.</title> <Abstract> <para> В данной главе приведено справочное описание макропроцессора <systemitem>m4</systemitem>, включая формат вызова, синтаксис использования, встроенные макрокоманды. </para> <para> Здесь описана версия <systemitem>GNU m4</systemitem>, отличающаяся от стандартного макропроцессора <link linkend="tetech-m4--m4"></link>, входящего в поставку большинства UNIX-систем, наличием большого числа функциональных расширений, открытостью и переносимостью кода (доступен под любые платформы). </para> </Abstract> &lib-m4-ref-desc.sgm; &lib-m4-ref-cmd.sgm; </Section> Ссылки
Статья реплицируется в SMWiki, SBWiki, RDWiki, GZWiki, DPWiki, HRWiki, CBWiki, ORWiki, RAWiki, ITWiki, CRMWiki, NordeaWiki, EvolWiki, TMSWiki.
Любые правки этой статьи будут перезаписаны при следующем сеансе репликации. Если у вас есть серьезное замечание по тексту статьи, запишите его в раздел «discussion». Репликация: База Знаний «Заказных Информ Систем» → «SGML Docbook» |
![]() |
![]() |
![]() |