Технология DocBook существует с 1991 года и к сегодняшнему дню принята на вооружение многими ИТ-компаниями. Независимость от конкретного поставщика, открытость для расширений, отделение контента от дизайна, подкрепляемые свободно распространяемым инструментарием и обширной справочной литературой, вот уже более десяти лет подогревают интерес к DocBook, используемой в организациях, заинтересованных не только в парадной документации, но и в систематическом документировании своей деятельности.

Наблюдательный пользователь может обнаружить в Сети множество документов с однотипной навигацией между страницами при помощи ссылок Prev, Next, Up, Top, причем один и тот же документ может предлагаться в нескольких форматах: каскадный HTML, единый HTML, PDF (рис. 1).

Ясно, что документы в разных форматах генерируются из одного источника. Из какого? Чтобы это узнать, заглянем в «потроха» — в код HTML:

Копнув еще глубже, обнаруживаем, что DocBook используют многие авторитетные компании: Sun Microsystems, Hewlett-Packard, Red Hat, издательство O?Reilly & Associates, консорциумы W3C (www.w3c.org) и OASIS (www.oasis-open.org). На DocBook написана (или переведена) документация на Linux, FreeBSD, PHP, Apache.

Чем же так привлекательна эта технология и кому она может быть полезна? В самом деле, ведь существует множество программ для подготовки текстов (начиная с Microsoft Word), настольных издательских систем (например Xerox Ventura Publisher, Adobe PageMaker) и языков разметки (unix nroff/troff, TeX/LaTeX, тот же HTML). Свои достоинства DocBook унаследовал от XML:

• простой HTML-подобный язык разметки;
• четкое разделение контента и верстки, чего нет в HTML;
• мощный набор стандартов и поддерживающих их инструментов, позволяющих обрабатывать тексты (XSLT, XSL-FO, Xpath);
• независимость от коммерческих производителей и их стандартов, наличие свободно распространяемого инструментария;
• расширяемость.

Роль HTML как основного носителя информации в Internet невозможно переоценить. Этот язык разметки оказался невероятно удачным — простым, удобным, выразительным и технологичным. Миллионы людей получили возможность поделиться своими знаниями, опубликовав их в виде HTML-страниц. Но «вольность» HTML, соответствующая анархическому духу Сети, в корпоративной среде становится недостатком. HTML-документы плохо поддаются унификации. Технически это связано с тем, что в HTML присутствуют как структурные тэги (например

,

,

, ), так и оформительские (например , , ). В результате каждый автор волен «раскрасить» документ так, как ему нравится, что усложняет создание корпоративных библиотек. (Сущий кошмар в этом смысле представляют документы, экспортированные в формат HTML из Microsoft Word.) Конечно, можно заставить авторов пользоваться только ограниченным набором структурных тэгов, но лучше, чтобы это ограничение срабатывало на уровне языка разметки, а не на дисциплинарном.

Кроме того, HTML недостаточно четко формализован. Конечно, есть официальный стандарт W3C, но в реальности и браузеры, и Web-мастера широко используют нестандартные конструкции. Это затрудняет автоматизированную обработку HTML-документов, без которой нельзя обойтись, когда речь идет о корпоративной среде.

Благодаря опоре на XML в DocBook отсутствует целый ряд недостатков, присущих HTML-инструментарию. Так, в DocBook присутствуют только структурные тэги. Их много (около 400), но ходовых всего пара десятков: вместо

, вместо , вместо

, вместо

и т.д. Формат документа жестко выдерживается: например, каждому открывающемуся тэгу обязан соответствовать закрывающий . В противном случае ни одна программа такой документ обрабатывать не будет. Наконец, имея на входе четко структурированный документ, приспособленный к автоматизированной обработке, получение выходного документа, оформленного в корпоративном стиле, в формате HTML, PDF, WinHelp или другом, становится делом техники — при том, что уже есть большая часть инструментария, стандартные XSL-процессоры. Например, вот как выглядела бы данная статья в виде исходного текста DocBook:

Несложно и интуитивно понятно.

Инструментарий

Для работы с DocBook понадобятся: редактор для набивки исходного текста и конвертеры для преобразования исходного текста в выходные форматы. Для ввода исходного текста подойдет обычный текстовой редактор. Если он работает с XML — отлично: это обеспечит вам дополнительный сервис, например «на лету» обнаруживать ошибки разметки. Максимум комфорта даст специализированный XML-инструментарий. Например, в меню программного продукта Altova Authentic слово DocBook присутствует в явном виде. К тому же Desktop Edition этого продукта является бесплатным. Далее сохраните текст в файле с расширением «.xml». Если редактор не проверяет корректность XML-документа, то самый простой способ его проверить — открыть при помощи Internet Explorer. Если все в порядке, IE отобразит документ в виде структурного дерева, в котором можно сворачивать и разворачивать отдельные ветки, соответствующие разделам документа.

Конвертеры — это XSLT-процессор и скрипты. И то и другое доступно в составе дистрибутива практически любой более-менее современной версии ОС Linux. Скрипты постоянно развиваются: например, в версии 1.68 исправлены огрехи в предметном указателе на русском языке, поэтому их стоит сразу обновить, загрузив последнюю версию (docbook.sourceforge.net/projects/xsl) и развернув архив на сервере.

Для преобразования исходного документа в выходной формат надо набрать команду:

$ xsltproc /usr/docbook/xsl-stylesheets/html/chunk.xsl article.xml

где:

- xsltproc — вызываемая программа, XSLT-процессор (один из нескольких возможных);

- /usr/docbook/xsl-stylesheets — это то место на сервере, где размещены XSLT-скрипты;

- html/chunk.xsl — один из вариантов генерации выходного документа;

- article.xml — исходный документ DocBook.

Готово! В текущем каталоге должны появиться HTML-файлы, по одному на раздел статьи и общее оглавление.

Настройка

Первый, самый простой уровень настройки — это выбор стартового скрипта. В приведенном ранее примере таковым является html/chunk.xsl — он наиболее востребованный, но не единственный. Более широкие возможности для управления внешним видом выходного документа предоставляют параметры, которых только для chunk.xsl насчитывается более 200. Пример: заставим выделять в отдельный файл первый раздел документации и зададим кодировку выходного документа windows-1251 вместо UTF-8, принятой по умолчанию:

$ xsltproc --param chunk.first.sections 1

> --stringparam chunker.output.encoding windows-1251

> /usr/docbook/xsl-stylesheets/html/chunk.xsl article.xml

Для реальной работы захочется задать как минимум десяток параметров, однако делать это через командную строку неудобно. Поэтому можно использовать так называемый «XSL-драйвер». В результате различных манипуляций можно добиться того, что сгенерированные HTML-страницы будут полностью удовлетворять вашим представлениям об эстетике и эргономике или просто соответствовать принятому корпоративному стилю (рис. 2).

Максимальной гибкости в использовании XSL-скриптов можно достичь, если подменять не только значения параметров, но и код, используемый для обработки тех или иных тэгов. Например, если вас не устраивает то, как отрабатывается тот или иной шаблон, вы просто копируете его из файла в каталоге /usr/docbook/xsl-stylesheets в свой драйвер и правите его так, как считаете нужным. Шаблоны, которые вы напишете, перекроют импортируемые. Похожим способом можно не только менять обработку существующих тэгов, но и вводить свои собственные!

Возможна ситуация, когда ваш документ окажется правильным с точки зрения XML, но не будет соответствовать схеме DocBook. Например, в нем будут придуманные пользователем тэги. XSL-скрипты ведут себя очень разумно: содержащийся внутри таких тэгов текст попадет в выходной документ, но при этом будет выделен красным цветом. Теперь осталось написать свой обработчик (xsl:template) для изобретенного тэга и вставить его в свой драйвер, а еще лучше — импортировать из отдельного файла.

Выходные форматы

Преобразование из DocBook в HTML в стандартных XSL-скриптах отработано практически идеально. Нет проблем также с генерацией в Windows HTML Help. Скрипт htmlhelp/htmlhelp.xsl создает набор HTML и необходимые служебные файлы. После этого запускается Help-компилятор hhc.exe, который Microsoft распространяет свободно, и порождается HTML Help.

В том, что касается генерации PDF, проблемы, увы, есть. И если для документов на английском языке получить выходной документ приемлемого качества довольно просто, то добиться того же для документа на русском — занятие не для слабонервных. Сначала DocBook преобразуют в промежуточный формат, для которого уже есть готовая программа преобразования в PDF. Таких промежуточных форматов как минимум два: XSL-FO и TeX. Стандартные XSL-скрипты поддерживают преобразование в XSL-FO, но дальше начинаются проблемы. Хорошо известны два свободно распространяемых транслятора из XSL-FO в PDF: PassiveTeX и Apache FOP (xml.apache.org/fop). Первый никогда не рассматривался его автором в качестве серьезного продукта, второй выглядит посолиднее, но, увы, последняя версия FOP 0.20.5 была выпущена еще в июле 2003 года.

Из коммерческих FOP-процессоров, пожалуй, лучшим на сегодняшний день является продукт XEP от компании RenderX ценой около 300 долл. Это зрелый продукт и проблем с русским языком у него нет, благо вся команда разработчиков русскоязычная. К сожалению, «из коробки» кириллические шрифты в нем не работают и нет инструкции, которая толково объясняла бы, как их включить. Но если догадался, то дальше все работает гладко, есть даже переносы для русского текста.

Вторая альтернатива — промежуточное преобразование в LaTeX. Стандартные XSL-скрипты его не поддерживают, но есть, например, db2latex — также пакет XSL-скриптов, который можно заставить делать то, что нужно. «Из коробки» он с русскими буквами тоже не работает — требуется настроить XSLT-драйвер. Сгенерированный документ в формате LaTeX можно преобразовать в PDF командой pdflatex, также штатно имеющейся в ОС Linux. После этого русский текст появляется, но до удовлетворительного результата еще далеко: остаются огрехи в графике, в выравнивании текста, в закладках PDF и т.п. Также в db2latex не поддерживается атрибут morerows — в таблицах невозможно объединять ячейки по вертикали. К тому же стало ясно, что для доведения этого варианта до ума не обойтись без глубокого изучения TeX/LaTeX.