Subscribe.Ru : Linux Gazette на русском

Написание документаци, часть III: DocBook/XML

Автор: (C) Кристоф Шпиль [Christoph Spiel]
Перевод: (C) С. Скороходов

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

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

В документах DocBook "текст" означает скорее "текстовые данные". В этом смысле, о документе DocBook лучше думать, как о базе данных, сохраняющей "читабельность" [human-readable].
Как стандарт, DocBook предписывает и то, какую внутреннюю структуру должны иметь документы с верной структурой [valid documents], и то, как они должны "выглядеть". Я написал "выглядеть" в кавычках потому, что применение документов DocBook не ограничено просмотром на экране. Такие документы могут быть трансформированны и в поток речи, например, в навигационной системе автомабиля (Представьте, как Ваша SUV спрашивает: "Желаете установить KDE3 прямо сейчас?").
В ходе преобразования в какой-либо выходной формат документы DocBook тщательно проверяются на соответствие определенной структуре. Эта структура определена в так называемом описании типа документа, сокращенно -- DTD (document type description).
Изменяя DTD, на документ в формате DocBook можно наложить практически любые ограничения. Например, организационный комитет какой-либо научной встречи может принять такую DocBook DTD, что все статьи в протоколах конференции будут выглядеть одинаково и содержать необходимую информацию об авторах.

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

Благодаря своей структуре, документы формата DocBook можно легко созавать и модифицировать программными средствами, а также по ним удобно проводить автоматизированный поиск.
Для доступа к соответствующим XML документам мы, например, можем загрузить модуль XML::DOM в программу на Perl или служащий тем же целям модуль xml.dom в Python.

Для преобразования XML World Wide Web Consortium (W3C, http://www.w3c.org) даже определил специальный язык, названный XSLT (посмотрите, например, http://www.w3.org/TR/xslt and http://www.oasis-open.org/cover/xsl.html). XSLT сам определен в рамках SGML, что делает XML и XSL очень похожими: сплошные угловые скобки:).
Для преобразования DocBook в HTML, TeX, GNU Texinfo и многие другие -- включая аудио -- форматы существует множество инструментов. Это тоже непохоже на рассмотренные ранее форматы, для обработки которых имелось лишь одно приложение.
Популярные средства преобразования (трансляторы):
- OpenJade (http://openjade.sourceforge.net/) использует для преобразования DSSSL -- Lisp'одобный язык, описывающий преобразование XML-DocBook в HTML, TeX и т.д. Дополнительная информация по адресам: http://www.jclark.com/dsssl/ и http://www.oasis-open.org/cover/dsssl.html и
- Saxon (http://saxon.sourceforge.net/), делающий то же самое с помощью XSL.
Установка обеих программ, включая необходимые стилевые таблицы DSSSL и стилевые таблицы XSL -- дело достаточно непростое, так что начинающим я бы советовал попробовать пакеты .deb или .rpm.

Оба набора программ являюстя многоцелевыми трансляторами и, таким образом, не ограничены преобразованиями документов 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

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

</article>

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

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

chapter (глава), sect1 (раздел уровня 1), ..., sect6

заголовок

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

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

</chapter>

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

para (абзац)

<para>

текст абзаца

</para>

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

programlisting (листинг программы)

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

</programlisting>

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

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

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

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

Неупорядоченный список [Itemized List]
<itemizedlist>

    <listitem>

        Первый элемент списка

    </listitem>

    <listitem>

        Второй элемент списка

    </listitem>

    ...

</itemizedlist>
Нумерованный список [Enumerated List]
<enumeratedlist>

    <listitem>

        Первый пункт

    </listitem>

    <listitem>

        Второй пункт

    </listitem>

    ...

</enumeratedlist>
Список описаний/определений [Description List]
<variablelist>

    <varlistentry>

        <term>первый термин </term>

        <listitem>

             первое определение

        </listitem>

    </varlistentry>

    <varlistentry>

        <term>второй термин</term>

        <listitem>

             второе определение

        </listitem>

    </varlistentry>

    ...

</variablelist>

Тэги прямого форматирования [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 очень "многословен". Если не использовать специальный редактор, то объем вводимого вручную текста очень велик.

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

Norman Walsh and Leonard Muellner, DocBook: The Definitive Guide (Всеобъемлющее руководство), O'Reilly & Associates, first edition, ISBN: 156592-580-7 at Amazon. Можно вять и в сети (второе издание)
Веб-сайт DocBook
Сайт Norman Walsh'а (председателя управляющего комитета [steering committee] по DocBook)
Комитет по 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

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

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

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

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