Цитирую"Всеобемлющее руководство по 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 и многие
другие -- включая аудио -- форматы существует множество
инструментов. Это тоже непохоже на рассмотренные ранее форматы,
для обработки которых имелось лишь одно приложение.
Популярные средства преобразования (трансляторы):
Установка обеих программ, включая необходимые стилевые таблицы
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-книг
разобраться в множестве элементов, определяемых стандартом,
предлагается набор полезных и употребительных тэгов.
Эти теги определяют самый "внешний" элемент любого документа.
book
- <book>
I<абзацы или главы>
</book>
article
- <article>
I<абзацы или разделы первого уровня [level 1 sections]>
</article>
Структурные тэги делят документ на логические части -- главы,
разделы, абзацы и т.д.
chapter
(глава), sect1 (раздел уровня 1), ...,
sect6
- <chapter id = "метка">
заголовок
за которым следуют
абзацы или разделы уровня N+1
</chapter>
Определяет раздел. Обычно, элемент-глава или элеметн-раздел
несет атрибут id, который дает возможность
ссылаться на данный элемент, например так: <xref linkend =
"метка"></xref>.
-
-
para
(абзац)
- <para>
текст абзаца
</para>
Формирует абзац из нескольких строк текста. Этот элемент --
"рабочая лошадка" многих документов.
programlisting
(листинг программы)
- <programlisting role = "язык">
текст программы
</programlisting>
Воспроизводит значительный отрывок программного текста с
сохранением разбиения на строки. Предполагается, что программа
написана на языке, указанном в атрибуте role.
Имейте в виду, что внутри programlisting все
специальные символы сохраняют свое значение!
Создают списки трех обычных типов.
Пункты списка [items] и определения [definitions]
обычно образуются из одного или более абзацев, но могут содержать и
листинги программ. Термины [terms] обычно состоят из одного
или более слов, но не абзацев.
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
|