Написание документаци, часть III: DocBook/XML
 
Автор: (C) Кристоф Шпиль [Christoph Spiel]
Перевод: (C) С. Скороходов


Цитирую"Всеобемлющее руководство по DocBook" (подробности -- в разделе Дополнительные материалы): DocBook представляет собой систему для написания структурированных документов с использованием SGML или XML. В дальнейшем я сосредоточусь на XML-варианте DocBook, поскольку вариант, использующий SGML, постепенно выходит из употребления.

По сравнению с системами, которые обсуждались раньше (статьи про POD и LaTeX/latex2html), развитие DocBook происходило на базе несколько иной идеологии:

Эти специфические черты DocBook намекают на такое применение, которое если и не невозможно, то крайне затруднительно реализовать в документах POD или LaTeX.

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

Синтаксис

Синтаксис DocBook/XML напоминает HTML. Фундаментальное отличие между ними -- строгость, с которой требуется выполнение синтаксических правил. Многие HTML-браузеры в высшей степени терпимы к "незакрытым" [unterminated] элементам и обычно безмолвно игнорируют неизвестные элементы и атрибуты. Трансляторы DocBook/XML отвергают не соответствующие DTD входные данные отказываясь в этом случае выдавать какие-либо выходные данные. Отказ сопровождается подробным отчетом об обнаруженных ошибках.

DocBook/XML имеет несколько "наречий", отличающихся интерпретацией закрывающих тэгов. Наиболее "многословный" диалект всегда закрывает тэг <tag> с помощью </tag>. Другой вариант допускает сокращение закрывающего тэга до </>, в то время, как третий вообще разрешает опускать закрывающий тэг в пустых элементах. Я предпочитаю "выписывать" все тэги, стиль, который доказал свои преимущества для таких грубоко вложенных структур, как, например, вложенные списки. Поэтому в этой статье будет встречаться только форма <tag> ... </tag>.

Специальные символы записываются с помощью привычных соглашений об амперсанде & и точки с запятой ;, как и в HTML. Наиболее часто употребимые специальные символы:

Комментарии заключаются между "спецскобками" <!-- и -->.

Структура документа

Как уже говорилось, документы DocBook должны соответствовать заданной в DTD структуре. В начале каждого документа выбирается конкретная DTD:

    <!DOCTYPE                                       (1)
     book                                           (2)
     PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"    (3)
     "/usr/share/sgml/db41xml/docbookx.dtd"         (4)
     [ ]                                            (5)
    >

Для наглядности я разбил заключенное между "<" и ">" выражение на строки и пронумеровал их.

В части (1) говорится, что мы собираемся выбрать DTD. Часть (2) определяет элемент book, который становится корневым элементом нашего документа. В части (3) идентификатор PUBLIC сообщает транслятору местоположение DTD на данном конкретном компьютере. Квадратные скобки, составляющие часть (5), могут содержать так называемые определения сущностей [entity definitions], но, поскольку в введении мне не хочется вдаваться в детали, эта часть оставлена пустой.

Итак, наш текст начинается с корневого элемента, в данном случае с book. То, какие элементы могут появится внутри book определяется в DocBook DTD. Это может быть, например, bookinfo или chapter. Исчерпывающий перечень разрешенных элементов можно узнать из "Всеобъемлющего руководства". Элементы, которые могут появится внутри bookinfo или chapter определены в DocBook DTD, как и все другие элементы. Единственный способ составления правильного [valid] документа -- следование предписаниям DTD.

Хотя в первый момент правила могут показаться обременительными (Правила? Черт бы их побрал, эти правила!), но они играют ключевую роль в доступе к документам из программ. Поскольку документ соответствует DTD, то вся последующая обработка может использовать это обстоятельство. Какая радость для пишущих программы-обработчики! Признаю, что число элементов и их взаимоотшения понять непросто. Впрочем, эти взаимоотношения вполне логичны: глава [chapter] может содержать один или несколько (вводных) абзацев и один или несколько разделов первого уровня [level 1 sections]. С другой стороны, ни один раздел не может включать главу -- что было бы нелепо. Изучению DocBook может также помочь экземляр "Всеобъемлющего руководства", "поселившийся" рядом с клавиатурой. Ниже приводится краткая подборка часто используемых тэгов.

Вот совсем коротенький, но полный документ DocBook.

    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
                          "/usr/share/sgml/db41xml/docbookx.dtd" []>
    <book>
        <bookinfo>
            <title>XYZ (версия 0.8.15) Руководство пользователя</title>
        </bookinfo>
        <chapter id = "chapter-introduction">
            <title>Введение</title>
            <para>
                Это глава содержит краткое введение в XYZ.
            </para>
            <sect1 id = "section-syntax">
                <title>Syntax</title>
                <para>
                    Раздес содержит обзор синтаксиса языка XYZ.
                </para>
            </sect1>
            <sect1 id = "section-core-library">
                <title>Основная библиотека</title>
                <para>
                    Использование некоторых основных библиотечных функций
                    возможно даже если программа XYZ не загружает
                    дополнительные библиотеки.
                </para>

            </sect1>
        </chapter>
        <chapter id = "chapter-commands">
            <title>Команды</title>
            <sect1 id = "section-interactive-commands">
                <title>Команды диалогового режима</title>
                <para>
                    ...
                </para>
                <sect2 id = "section-interactive-commands-argumentless">
                    <title>Команды, не требующие аргументов</title>
                    <para>
                        ...
                    </para>
                </sect2>
            </sect1>
            <sect1 id = "section-non-interactive-commands">
                <title>Команды, доступные в пакетном режиме</title>
                <para>
                    ...
                </para>
                <sect2 id = "section-non-interactive-commands-argumentless">
                    <title>Команды, не требующие аргументов</title>
                    <para>
                        ...
                    </para>
                </sect2>
            </sect1>
        </chapter>
    </book>

Полезные тэги

Для того, чтобы помочь честолюбивому автору DocBook-книг разобраться в множестве элементов, определяемых стандартом, предлагается набор полезных и употребительных тэгов.

Тэги корневого раздела [Root Section]

Эти теги определяют самый "внешний" элемент любого документа.

book
<book>
  I<абзацы или главы>

</book>

article
<article>
  I<абзацы или разделы первого уровня [level 1 sections]>

</article>

Структурные тэги [Sectioning Tags]

Структурные тэги делят документ на логические части -- главы, разделы, абзацы и т.д.

chapter (глава), sect1 (раздел уровня 1), ..., sect6
<chapter id = "метка">

заголовок

за которым следуют

абзацы или разделы уровня N+1

</chapter>

Определяет раздел. Обычно, элемент-глава или элеметн-раздел несет атрибут id, который дает возможность ссылаться на данный элемент, например так: <xref linkend = "метка"></xref>.

para (абзац)
<para>

текст абзаца

</para>

Формирует абзац из нескольких строк текста. Этот элемент -- "рабочая лошадка" многих документов.

programlisting (листинг программы)
<programlisting role = "язык">

текст программы

</programlisting>

Воспроизводит значительный отрывок программного текста с сохранением разбиения на строки. Предполагается, что программа написана на языке, указанном в атрибуте role. Имейте в виду, что внутри programlisting все специальные символы сохраняют свое значение!

Тэги, образующие списки [List-Making Tags]

Создают списки трех обычных типов.

Пункты списка [items] и определения [definitions] обычно образуются из одного или более абзацев, но могут содержать и листинги программ. Термины [terms] обычно состоят из одного или более слов, но не абзацев.

Тэги прямого форматирования [Inline Markup Tags]

emphasis (выделение)
<emphasis>выделяемый текст</emphasis>

Делает небольшую часть документа, обычно -- единичное слово, выделяющейся на фоне окружающего текста.

filename (имя файла)
<filename>имя файла или каталога</filename>

Слово оформляется, как имя файла.

literal
<literal>литерал</literal>

<literal role = "классификатор">что-либо, передаваемое буквально, без обработки</literal>

Помечает слово, как литеральное выражение (т.е. выражение, не обрабатываемое транлятором, а передаваемое "на выход" в неизмененном виде). Используйте этот тэг в лишь в самом крайнем случае, когда не годится ни один из более конкретных тэгов. Для того, чтобы успокоить нечистую совесть, literal часто дополняется атрибутом role, который более точно описывает, что он собой прествавляет.

replaceable (заменяемое)
<replaceable>замещающее имя</replaceable>

Помечает мета-переменную.

title (заголовок)
<title>заголовок</title>

Содержит имя раздела или другого формального элемента, например таблицы.

Перекрестные ссылки

Перекрестные ссылки ссылаются на другие части того же самого документа DocBook или на другие документы, находящиеся в World Wide Web. В первом случае ссылка может указывать на все элементы, несущие атрибут id, во втором случае ссылка задается, как универсальный локатор ресурса (URL).

link
<link linkend = "на что ссылаемся [target]">содержимое</link>

Создает (гипер)ссылку на место в текущем документе, задаваемое через атрибут target.

ulink
<ulink url = "полный URL">содержимое</ulink>

Создает гиперссылку на документ WWW, указанный в полном URL. Полный URL должен задавать протокол, например http://.

xref
<xref linkend = "target"></xref>

Задает (гипер)ссылку на место в текущем документе, иденитифицируемое, как target. Транслятор сам добавляет текст вокруг xref. Например, ссылка xref на раздел может быть "украшена" словами "смотри раздел".

О чем я умолчал

М-м, да тонны всего, но только для того, чтобы изложение было легким и никого не отпугнуло. Вот некоторые важные элементы, используемые в DocBook, но не включенные в изложение:

Не затрагивалось и все, относящееся к изменению DTD или стилевых таблиц.

За и против

За
  • DocBook -- официальный стандат W3C
  • Доступ к тексту из программ (в том числе -- определяемых пользователем)
  • Богатая и выразительная разметка текста
Против
  • Медленная обработка
  • Формат DocBook очень "многословен". Если не использовать специальный редактор, то объем вводимого вручную текста очень велик.

Дополнительные материалы

В следующем месяце: Texinfo


Кристоф Шпиль [Christoph Spiel]

Крис руководит расположенной в Верхней Баварии (Германия) компанией, консультирующей по вопросам Open Source Software. Не смотря на то, что по образованию он физик (он получил ученую степень Доктора Философии в Мюнхенском Технологическом Университете), его главные интересы вращаются вокруг численных методов, гетерогенных сред программирования и разработки программного обеспечения. Связаться с ним можно по адресу [email protected].


Copyright (C) 2002, Christoph Spiel.
Copying license http://www.linuxgazette.com/copying.html
Published in Issue 75 of Linux Gazette, February 2002

Команда переводчиков:
Владимир Меренков, Александр Михайлов, Иван Песин, Сергей Скороходов, Александр Саввин, Роман Шумихин, Александр Куприн

Со всеми предложениями, идеями и комментариями обращайтесь к Сергею Скороходову ([email protected]). Убедительная просьба: указывайте сразу, не возражаете ли Вы против публикации Ваших отзывов в рассылке.

Сайт рассылки: http://gazette.linux.ru.net
Эту статью можно взять здесь: http://gazette/linux.ru.net/lg75/articles/rus-spiel.html