SGML Docbook

Ссылки сюда (7) →

DocBook — приложение SGML или XML (проще говоря — популярный набор тэгов), предназначенное для разметки документов, такое же, как HTML для разметки веб-документов. Но в отличие от HTML, Docbook не предоставляет информацию о визуальном представлении документа. Преобразованием Docbook документа в форматы, доступные для печатного или просто визуального представления занимаются различные утилиты, обычно осуществляющие такое преобразование на основе настраиваемых шаблонов, т. е. происходит настоящая изоляция структуры документа от визуального представления.

История

Docbook был рожден в 1991 году (первоначально — для облегчения переноса troff-меченой UNIX-документации), и, в разное время, развивался и поддерживался различными организациями:

1991-1994

HaL Computer Systems и O'Reilly & Associates (+большое влияние Novell и Digital).

1994-1998

Davenport Group (+большое влияние Novell и Sun). Эпоха расцвета Docbook.

1998- 

OASIS. Разработка официальных DocBook SGML V4.1 и DocBook XML V4.1.2. С 2001 года длится разработка DocBook V5.0 DTD.

Пример

Заголовок

Рассмотрим заголовок 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 — приложений):

• XML элементы должны быть всегда закрыты.
• XML элементы должны иметь правильную вложенность.
• значения атрибутов должны быть обязательно в кавычках.
• Это означает, что вы не можете использовать <BR> как в HTML, вы должны использовать <BR></BR>. Второе требование означает, что вы не можете использовать следующую конструкцию :

<B><A HREF="some_url">click here</B></A>

вы должны использовать правильную вложенность:

<B><A HREF="some_url">click here</A></B>.

Итак, заголовок состоит из

1. XML-декларации
2. Ссылки на DTD Docbook (соответствующей версии).
3. Внутреннего подмножества (Internal Subset) — то что находится внутри квадратных скобок. Там определяются все entity (объекты или подстановки), раскрывающиеся в литералы или содержимое файлов.

Комментарии

Комментарии оформляются стандартно для 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 или другой внешний файл можно оформить

• через системный идентификатор (system identifier), обычно трактуемый как имя файла (в SGML), или, как в XML, URI-некоторого ресурса
• или публичный идентификатор (public identifier), который должен внести некоторую степень косвенности в связь документа и его ссылки (как правило на DTD), т. е. освободить документ от необходимости (для целостности) сопровождать себя декларацией.

В XML-версии, обязательно предоставлять системный идентификатор (даже если есть публичный).

Публичные идентификаторы должны быть алфавитноцифровыми, и могут содержать

' ( ) + , - . / : = ?

а также пробелы и переводы строки. Главное — они должны быть глобально уникальными. Поэтому, принято использовать формальные публичные идентификаторы (Formal public identifiers, FPI), предложенные стандартом ISO 8879, правило формирования которых должно обеспечивать их уникальность:

prefix//owner-identifier//
text-class text-description//
language//display-version

где:

prefix

«+» или «-», в зависимости от того, зарегистрирован ли этот идентификатор или нет. Т.к. мало у кого есть право регистрировать публичные идентификаторы, большинство встречающихся публичных идентификаторов — незарегистрированы.

owner-identifier

Идентификатор владельца идентификатора — главное обеспечение уникальности. Если идентификатор не планируется официально регистрировать, то разумно сделать эту часть уникальной, основываясь например не на аббревиатуре организации, а на доменном имени, которое ей принадлежит.

Примеры:

+//ISO/IEC 9070/RA::A00002//...
+//IDN oreilly.com//...
-//OASIS//...
-//Davenport//...
-//IDN custis.ru//...

text-class

Тип документа. Наиболее распространенные типы:

DOCUMENT

SGML или XML документ

DTD

DTD

ELEMENTS

Набор деклараций SGML-элементов.

ENTITIES

Набор деклараций SGML-объектов (entities). A collection of entity declarations.

NONSGML

Данные не в SGML- (и соответственно не в XML-) формате.

text-description

Свободное текстовое описание (должно только не включать «//»).

language

Двухбуквенный ISO-код языка документа.

display-version

Описывает вариации документа для различных систем. Например для документа с FPI

-//ISO 8879-1986//ENTITIES Added Latin 1//EN

может быть XML-версия с FPI:

-//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 можно разделить на

структурные

книги, разделы, секции и т. п.

блочные

различные списки и параграфы.

строчные

форматирование внутристрочных элементов.

метаэлементы

вспомогательные метаэлементы, «атрибутирующие» другие элементы. В версии Docbookа 5.0, все такие элементы должны содержаться в метаэлементе «info»

Вложенность структурных элементов удобно наблюдать на следующей (гипертекстовой) диаграмме:

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).

Блочные элементы

Блочные элементы находяться ниже уровня структурных элементов, по сути, это элементы уровня параграфов: списки, замечания, синопсисы, таблицы, рисунки и т. п.

Списки

«calloutlist»

Список сносок и их описаний.

 <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>

«bibliolist»

Список библиографических ссылок.

«glosslist»

Список терминов (например, в глоссарии) и их определений.

<glossdiv>
   <glossentry>
    <glossterm id="db--association">ассоциированный объект</glossterm>            
    <glossdef><para>Объекты которые каким-либо образом связаны с другим объектом, 
      который в данный момент рассматривается как текущий. 
      Например: <quote>все неоплаченные требования к контрагентам данного менеджера</quote>. 
    </para></glossdef>
    </glossentry>
</glossdiv>

«itemizedlist»

Ненумерованный (маркированный) список.

 Процедура может работать в следующих режимах (значение параметра         <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»

Нумерованный список.

    Могут быть разные причины того, что подсистема не предоставляет доступа к системе:
    <orderedlist>
      <listitem><para>неверно указан адрес страницы internet,
           в результате чего фактически выполняется обращение к другой,
           также закрытой странице;</para></listitem>
      <listitem><para>ошибка (опечатка) во введенном пароле 
            - необходимо еще раз внимательно ввести пароль;</para></listitem>
      <listitem><para>ошибка во введенном пароле может заключаться в том, 
            что пользователь не переключил шрифт с русского на латинский или наоборот,
           а также режим ввода больших букв - необходимо проверить режим работы клавиатуры.
      </para></listitem>
    </orderedlist>

«segmentedlist»

Список для определения нескольких определенных параметров для разных обьектов. Например:

    <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>

«simplelist»

Самый простой (без сложного оформления), список. Может быть даже строчным, или построенным по колонкам.

          <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»

Список терминов и их определений.

<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>

Замечания

На самом деле, семантика разного типа заметок не сильно определена, и в основном, выбор типа заметки определяется или корпоративными правилами, или ожидаемым форматированием (например, разные типы заметок могут форматироваться блоками с разными графическими значками-предупреждениями).

«caution»

Предостережение. Как правило, связанное с действиями техники, чем с действиями людей (для чего предназначен «warning»).

 <сaution><para>Наверняка есть другие источники информации,  а также другая поступающая информация. 
          Так что этот список нуждается в расширении и доработке.
 </para></сaution>

«important»

Важно!

 <important><para>При загрузке все нулевые значения отрезаются и не вводятся!</para></important>

«note»

Замечание, пометка.

      <note><para>Этот размер различен для различных операционных систем и определяется
        для каждой из них отдельно.
      </para></note>

«tip»

Совет, подсказка.

   <tip><para>Каждый вопрос имеет ответ по умолчанию, который принимается 
          при нажатии кнопки <interface>Enter</interface>.</para></tip> 

«warning»

Предостережение, скорее относящееся к действиям пользователя (а не к свойствам оборудования или софта — это «caution»).

 <warning><para><emphasis>Нельзя</emphasis> получать новые версии файлов другим путем, кроме 
   как выполнением команд <systemitem>update</systemitem> или
   <systemitem>checkout</systemitem>. Копирование новых версий файлов 
   с другого компьютера может привести к потере данных!
 </para></warning>

Специальные блоки

«address»

Почтовый адрес.

«literallayout»

Преформатированный блок (без всякой семантики).

«programlisting»

Преформатированное окружение для текстов (или фрагментов текстов) программ или иных кодовых блоков (например, SQL-запросов).

  <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 &ne; 0 );
   </programlisting>

«screen»

Преформатированное окружение для различных ASCII-фрагментов, типа вывода текстовой консоли или «текстового скриншота» с telnet-интерфейса.

«screenshot»

Специальное окружение для элемента «Graphic», который и включает скриншот.

«synopsis»

Преформатированный блок для синопсиса вызова функций и команд.

                <synopsis>
                    cvs add -kb <replaceable>имя файла</replaceable>
                </synopsis>

Таблицы, рисунки, примеры

Версии элемента с префиксом «informal», означают отсутствия вложенного элемента «title» (заголовка).

«example», «informalexample»

Пример (чего-либо).

<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», «informalfigure»

Окружение для картинок/рисунков.

  <figure id="lib-cis-structure-pict">
    <title>Структура компонентов cis-forms</title>
    <graphic entityref="interface-structure.gif " align=center scale=100></graphic>
  </figure>

«table»(deprecated),«informaltable»(deprecated)

Таблица.

 <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>

Параграфы

«para»

Обычный параграф.

«formalpara»

Абзац с заголовком (включает элемент «title»).

«simpara»

Упрощенный параграф (не может включать других блочных элементов).

Уравнения

Есть элементы «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) можно сделать с помощью элемента «qandset»(deprecated), состоящего из элементов «questions»(deprecated) и «answers»(deprecated).

Остальные блочные элементы

«blockquote»

Блок-цитата.

    <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>

«cmdsynopsis»

Синопсис вызова команды.

«funcsynopsis»

Синопсис вызова функции.

«epigraph»

Эпиграф.

«highlights»(deprecated)

Краткие тезисы или ключевые моменты содержимого главы или раздела.

«msgset»

Набор сообщений об ошибках.

«procedure»

Процедура. Формальное описание алгоритма.

   <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»

Блок текста выделенный рамкой.

 <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

Текстовая строка, описывает операционную систему, к которой применим элемент и его содержимое.

Remap

Remap 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 — приложений:

• XML элементы должны быть всегда закрыты
• XML элементы должны иметь правильную вложенность
• Это означает, что вы не можете использовать <BR> как в HTML, вы должны использовать <BR></BR>. Второе требование означает, что вы не можете использовать следующую конструкцию :

<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>
 

Ссылки

• Слегка устаревший, но еще актуальный документ Ведении документации компании
• ЗИС::Ведение SGML-документации.
• Интерактивный HTML-Reference по Docbook.
• DocBook XSL: The Complete Guide

---

Статья реплицируется в SMWiki, SBWiki, RDWiki, GZWiki, DPWiki, HRWiki, CBWiki, ORWiki, RAWiki, ITWiki, CRMWiki, NordeaWiki, EvolWiki, TMSWiki.

---

Внимание! Данная статья выбрана для репликации во внешнюю базу знаний компании. Пожалуйста, не допускайте в этой статье публикацию конфиденциальной информации, ведения обсуждений в теле статьи, и более ответственно относитесь к качеству самой статьи — проверяйте орфографию, пишите по-русски, избегайте непроверенной вами информации.