АнатолийБелайчук bell@b-k.ru 2005 Анатолий Белайчук DocBook — технология подготовки документации, обладающая значимыми преимуществами перед традиционными средствами — текстовыми процессорами и настольными издательскими системами. Оборотная сторона богатых возможностей DocBook— сложность в первоначальном освоении, выборе и настройке инструментария. Цель данной статьи — указать путь, по которому можно с минимальными затратами сил, времени и денег внедрить DocBook в объеме, достаточном для того, чтобы оценить эту технологию по достоинству и извлечь из нее практическую пользу.

Все то, что автор хотел высказать, прежде чем приступить к делу.

DocBook — это система подготовки документации, основанная на технологиях XML и SGML. По сравнению с традиционными средствами — текстовыми процессорами (такими, как Microsoft Word) и настольными издательскими системами (например, Ventura Publisher) она обладает рядом преимуществ: в открытости, в возможности генерации выходных документов в разных форматах (в частности, HTML и PDF), в поддержке коллективной работы. DocBook нецелесообразно использовать для написания разовых, небольших по формату документов. Его преимущества максимально раскрываются там, где речь идет о качественной документации, разрабатываемой и дополняемой в течение длительного времени коллективом авторов. DocBook является стандартом де-факто для документации на свободно распространяемое программное обеспечение, его используют известные компании и организации: IBM, Microsoft, Hewlett-Packard, Sun, Novell, WWW Consortium, OASIS. DocBook полностью адаптирован к русскому языку. Подробнее о DocBook: docbook.ru.

Технология DocBook существует с 1991 г., проделав за это время значительную эволюцию: XML и XSL пришли на смену SGML и DSSSL, происходит постоянное развитие (а время от времени — и смена) инструментария. За прошедшие годы на тему DocBook написано огромное количество справочников, учебников, статей и инструкций. Проблема однако заключается в том, что эта документация частью устарела, частью противоречит друг другу. Это следствие того, что развитие DocBook происходит по модели OpenSource, без централизованного контроля. В результате инструкции зачастую ссылаются на инструментарий, который уже не развивается и пользоваться которым нецелесообразно. Еще одно затруднение, с которым сталкиваешься при первоначальном освоении DocBook — чрезвычайная обширность предмета. DocBook — это открытая и мощная технология, и ее можно приспособить для самых разных вещей. В результате при первоначальном знакомстве нелегко отличить магистральный путь использования DocBook от боковых дорог и живописных, но малохоженных троп. И наконец, при всем богатстве документации по DocBook, текстов на русском языке мало, а особенно плохо обстоит дело с начальными инструкциями для широкого круга читателей. Есть и специфические проблемы, связанные именно с русским языком, в частности, с кириллицей в выходных документах, ориентированных на печать. Перечисленные проблемы и послужили стимулом к написанию данной статьи.

Статья оформлена в стиле тема с вариациями: Основной текст представляет собой собственно обещанный кратчайший путь, пройдя которым вы собственными руками создадите документ DocBook и преобразуете его в HTML и PDF. Для этого инструкции, содержащиеся в основном тексте, надо выполнить последовательно, шаг за шагом. Вариации — это направления дальнейшего развития или способы, альтернативные предлагаемому. С их помощью вы сможете расширить возможности DocBook, но их исследование разумнее отложить на потом. Вариации оформлены в тексте следующим образом: Теоретически специализированные XML-редакторы предоставляют больший сервис Такой текст при первоначальном чтении можно или пропустить, или просто принять к сведению, и исследовать описанные в нем возможности уже после того, как достигнут основной результат. Цель такой организации материала — возможно быстрее получить первый результат, ведь это лучший способ подъема энтузиазма и у исполнителей, и у начальства. Статья содержит минимум пояснений, расчет делается не на формальные объяснения, а на освоение по образцу. Описание используемых в примерах тэгов и атрибутов DocBook содержится в основополагающем справочнике по тэгам DocBook: и в менее формальном справочнике на русском языке: .

Для работы с DocBook от вас потребуется определенная квалификация и компьютерные ресурсы: Вы должны быть хотя бы минимально знакомы с XML или HTML. Например, в статье не объясняются термины тэг, атрибут. В случае затруднений обращайтесь к справочной литературе. В качестве инструментальной платформы рассматривается Linux. В принципе инструментарий DocBook доступен для различных платформ, включая Windows и Mac, но для пошаговых инструкциях приходится выбирать один вариант (рассмотрение нескольких платформ вывело бы статью за рамки рассмотрения кратчайшего пути). Выбор Linux определяется тем, что весь необходимый для работы с DocBook инструментарий штатно с ним поставляется. Знание Linux требуются минимально-достаточное для того, чтобы суметь воспроизвести содержащиеся в тексте статьи команды. Предполагается, что у вас есть доступ к компьютеру, на котором установлен Linux (назовем его сервером). Мощность сервера и версия Linux существенной роли не играют. У вас должен быть рабочий каталог и доступ к командной строке. Если вы предпочитаете работать с текстовым или XML-редактором на персональном компьютере с отличной от Linux операционной системой, то у вас должна быть возможность копировать файлы на сервер или, оптимально, сделать рабочий каталог сервера доступным по сети через сетевой диск (т.е. запустить на сервере samba). Для того, чтобы просматривать результаты работы, у вас должна быть возможность копировать с сервера сгенерированные файлы или, оптимально, сделать рабочий каталог сервера доступным через веб-сервер (т.е. запустить на сервере apache). Для инсталляции или обновления инструментария вам кратковременно могут понадобиться полномочия суперюзера или помощь системного администратора, такими полномочиями обладающего. Вам понадобится доступ к Интернет, чтобы скачивать инструментарий. (Впрочем, он наверное у вас есть, раз вы читаете эту статью.) Инструментарий для генерации PDF требует наличия виртуальной машины Java. Рекомендуется Sun JRE или JRE версии не ниже 1.3. Для того, чтобы результаты работы представляли для вас практический интерес, подберите текст, на котором будете упражняться (будем называть его тестовым документом). Это может быть статья, заметка, фрагмент руководства. Хранящиеся в файле Microsoft Word, текстовом или любом другом, из которого вы сможете переносить текст методом cut-and-paste. Оптимальный размер — от 3 до 10 страниц.

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

Создайте в рабочем каталоге файл, руководствуясь следующим образцом:

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

Первый абзац первого раздела.

]]> Воспользуйтесь для этого обычным текстовым редактором. Подойдет notepad.exe, но не Word или другой текстовый процессор. Существуют специализированные XML-редакторы, и большинство из них умеет работать с DocBook. Теоретически они предоставляют больший сервис по сравнению с обычными текстовыми редакторами: например, автоматически проверяют правильность вводимых тэгов, предлагают выбор тэгов в зависимости от контекста. Но, с другой стороны, XML-редакторы трудно назвать простыми в использовании. К тому же трудно найти XML-редактор, у которого была бы русская версия. Редакторы же, у которых язык диалогов английский, малопригодны для рядовых пользователей. Инструментарий DocBook: docbook.ru/about/tools. Скопируйте приведенный выше фрагмент в буфер редактора, замените в нем текст названия, абзацев и т.д. на содержательный из тестового документа. Сохраните буфер в файле с именем article.xml.

Откройте файл при помощи веб-браузера (например Internet Explorer). Если все сделано правильно, вы увидите примерно следующую картинку: Если IE обнаружит ошибки, он их диагностирует, указав при этом номер строки и символа в строке. Исправьте обнаруженные ошибки. В предложенном образце опущена DTD-декларация, которая могла бы следовать во второй строке и выглядеть примерно так: ]]> Причины такого небрежения следующие: во-первых, для генерации выходных документов DTD-декларация не требуется, а во-вторых, пользоваться DTD надо, понимая что за ним стоит. В частности, что такое Public Identifiers, System Identifiers, DTD Entities и еще, желательно, XML Catalogs. Использование DTD имеет то преимущество, что это позволит проверить документ более качественно. Простейшая проверка, которую делает IE — это так называемая проверка на XML-валидность: соответствие открывающих-закрывающих тэгов и кавычки в значениях атрибутов. При наличии указания DTD можно будет программным образом проверить правильность взаимного расположения (вложенности) тэгов, отсутствие обязательных атрибутов и т.п. Кроме того, при наличии DTD вы сможете пользоваться стандартными мнемониками типа   и © или вводить свои собственные. DTD позволит также собирать документ из отдельных фрагментов, но для этого есть лучший способ — XInclude. При вводе исходного документа обращайте внимание на следующее: Документ должен начинаться с XML-декларации, как в приведенном примере. Кодировка может быть другой, например koi8-r, но, естественно должна соответствовать фактически используемой вами кодировке. Если вы вводите текст в Windows, оставьте кодировку windows-1251. Все открытые тэги должны аккуратно, с соблюдением вложенности, закрываться: <para> соответствует </para>, <title> — </title> и т.п. Атрибуты внутри тэгов, даже числовые, должны ставиться в кавычках (одинарных или двойных), как lang="ru" в приведенном примере. Если в вашем тексте встречается символ <, то замените его на <, а символ & на &. Альтернативно, например если нужно вставить в текст кусок программного или XML-кода, пользуйтесь следующей SGML-конструкцией: <![CDATA[здесь можно пользоваться любыми символами]]> Остальные мнемоники HTML, в частности   (явный пробел) XML по умолчанию не понимает. Используйте числовой код, например   вместо  . Если ваш браузер не умеет работать с XML, ничего страшного, ошибки чуть позже диагностирует XSL-процессор.

Скачайте последнюю версию XSL-скриптов DocBook и распакуйте архив на сервере. Разработка ключевых компонент DocBook, в частности XSL-скриптов и DTD, ведется в рамках Open Source проекта, домашняя страница которого docbook.sourceforge.net. Альтернативно, XSL-скрипты можно инсталлировать из RPM-пакета docbook-style-xsl, который скорее всего входит в состав вашего дистрибутива Linux. Но мы рекомендуем скачать и установить последнюю версию. Желающих изучить XSL адресуем к книге . Местоположение каталога значения не имеет, но для определенности в дальнейших инструкциях мы будем предполагать, что скрипты находятся в каталоге /usr/local/docbook-xsl-1.68.1 (1.68.1 — номер версии).

Наберите команду xsltproc --version. xsltproc не единственный XSLT-процессор, который можно использовать для DocBook, но он быстр, достаточно надежен и доступен на платформе Windows. Инструментарий DocBook: docbook.ru/about/tools. Если программа не запустилась, проверьте наличие RPM-пакет libxslt и если он не установлен, проинсталлируйте стандартными средствами Linux.

Наберите команду: Как свидетельствует сообщение программы, в текущем каталоге образовался файл index.html. Открыв его в браузере, вы увидите примерно следующее: Стандартные XSL-скрипты поддерживают специальный вариант трансляции в HTML — для последующего преобразования в Microsoft HTML Help. Вместо html/chunk.xsl задайте htmlhelp/htmlhelp.xsl, в результате образуется набор HTML-файлов и служебные файлы, которые понимает штатный Help-компилятор hhc.exe. Посмотрим на HTML-код образовавшегося файла: ]]> Видно, что русские буквы превратились в числовые коды. Чтобы получить текст в нормальной кодировке (например, windows-1251), зададим соответствующий параметр: /usr/local/docbook-xsl-1.68.1/html/chunk.xsl article.xml Writing index.html for article $ ]]> Ключ --nonet запрещает обращение в Интернет за XSL-скриптами. Обработка DocBook довольно трудоемка, поэтому предпочтительно чтобы скрипты находились на сервере локально. С этим ключом вы будете уверены, что берутся только локальные скрипты, а обращения в Интернет будут диагностироваться и блокироваться. Ключами --param и --stringparam задают значения числовых и строковых параметров соответственно, управляя таким способом внешним видом выходного документа.

Для того чтобы дальше работать над внешним видом выходного документа, вам понадобится задать значение целой серии параметров. Делать это через командную строку неудобно, поэтому создайте файл с именем docbook.xsl и следующим содержимым: ]]> Это т.н. XSL-драйвер, в дальнейшем с его помощью вы сможете не только задавать параметры, но и проводить более глубокую настройку DocBook. DocBook — это максимально открытая система, рассчитанная на то, чтобы вы могли приспособить ее для своих нужд. Для этого имеется набор средств. В порядке от простого к сложному вы можете влиять на следующие элементы: простые числовые и строчные параметры XSL-скриптов форматирование (при помощи CSS) более сложные параметры, требующие использование выражений XPath наборы атрибутов XSL (xsl:attribute-set) XSL-шаблоны (xsl:template) расширение схемы и обработка собственных тэгов Переопределенные параметры, наборы атрибутов, шаблоны — все они записываются в XSL-драйвер. Вопросы кастомизации DocBook подробнейшим образом рассматриваются в книге . Запустите XSL-процессор: Командная строка упростилась, а результирующий файл должен остаться без изменений.

Перенесите контент из тестового документа в article.xml. Для этого вам понадобится изучить тэги DocBook. Простейший способ — воспользоваться каким-нибудь образцом, например исходным текстом этой статьи. Для более систематического изучения тэгов DocBook воспользуйтесь справочниками и .

Поэкспериментируйте с параметрами, приведенными в справочнике . Разберитесь с разбиением выходного документа на файлы, автонумерацией разделов, автоматическими оглавлениями. Значения параметров задавайте в XSL-драйвере. Документация на DocBook XSL и, в частности, на параметры, содержится в дистрибутиве, который вы скачали. Она доступна также на сайте docbook.sourceforge.net. Привяжите к HTML-файлу стиль CSS при помощи параметра html.stylesheet. В качестве образца можете использовать CSS-файл этой статьи. Значения параметров можно задавать двумя способами: windows-1251 ]]> Обратите внимание, что в варианте с select необходимо различать текстовые и числовые параметры: для текстовых надо задавать одни кавычки внутри других, а для числовых нет. Во втором варианте значения и тех, и других задаются одинаково, поэтому он менее подвержен случайным ошибкам. DocBook позволяет из одного исходного документа создавать выходные документы не только в разных выходных форматах (о чем пойдет речь далее), но и с разным содержимым. Например, вы можете из одного исходного текста выпускать техническую документацию для разных модификаций вашей продукции, а в случае документации на программное обеспечение — инструкции для эксплуатации на разных системно-аппаратных платформах. Чтобы воспользоваться этой возможностью, вы должны пометить фрагменты текста, которые должны включаться условно, с помощью атрибутов, например: os — операционная система, userlevel — уровень квалификации пользователя (см. ). После этого вы запускаете XSL-процессор, задавая скрипт profile-chunk.xsl вместо chunk.xsl и выбирая желаемый вариант генерации при помощи параметров.

Скрипт chunk.xsl генерирует множество HTML-файлов. Такой формат удобен для онлайнового просмотра, но не для печати. Чтобы это исправить, скопируйте docbook.xsl в print.xsl и замените в файле print.xsl chunk.xsl на onechunk.xsl. Чтобы файлы, сгенерированные при помощи docbook.xsl и print.xsl, не перетирали друг друга, добавьте параметр: ]]> Запустите XSL-процессор: Настройте этот вариант генерации при помощи параметров: Подберите параметры оглавления, более подходящие для монолитного HTML. Скопируйте default.css в print.css и привяжите print.css к документу параметром html.stylesheet. В файле print.css подберите стили оформления, более подходящие для печати, в частности, уберите цвета и задайте CSS-свойства, управляющие разбиением на страницы: page-break-before, page-break-after, page-break-inside. Для вывода на печать больше подходит не формат HTML, а PDF. Получившийся монолитный HTML-файл вы можете преобразовать в PDF, например, при помощи Adobe Acrobat Distiller. Таким способом можно добиться неплохого результата с точки зрения внешнего вида документа, но в результирующем PDF-файле не будет гипертекстовых закладок, а в оглавлении не будет номеров страниц. Если для вас эти недостатки не критичны, можете на этом остановиться. Более корректный, но и намного более тяжелый способ генерации PDF из DocBook, при котором сохраняется структура документа и учитываются особенности вывода на печать (например отступы под переплет при двусторонней печати) рассматриваются в следующих разделах.

XSL-скрипты, которыми мы до сих пор пользовались, не умеют напрямую транслировать DocBook в PDF. Процесс распадается на два шага: Стандартные скрипты преобразуют DocBook в XSL-FO. Для преобразования XSL-FO используются стандартные FO-процессоры. Мы будем использовать процессор XEP компании RenderX (www.renderx.com). Альтернативные пути преобразования используют DSSSL скрипты и/или TeX в качестве промежуточного формата. Но на сегодняшний день XSL-FO — наиболее прогрессивная и активно развиваемая технология. Существуют бесплатные варианты XSL-FO процессоров, самые известные из них Apache FOP и PassiveTex. Но они уступают RenderX XEP по функциональности, к тому же обе эти разработки заморожены (по состоянию на начало 2005 г.) и поэтому перспективы их сомнительны. Сильная сторона RenderX XEP — полноценная поддержка русского языка, включая расстановку переносов в русском тексте. Скачайте бесплатную персональную версию процессора. Заполните регистрационную форму с вашим именем и email и получите лицензионный ключ. Персональная версия отличается от коммерческой тем, что вставляет логотип RenderX внизу каждой сгенерированной страницы. Для целей данной статьи этого достаточно, а для промышленной эксплуатации понадобится приобрести коммерческую лицензию. Технически для перехода на коммерческую лицензию надо просто скопировать файл с лицензионным ключом, полученный от RenderX. Распакуйте полученный архив и проинсталлируйте его: Вы можете выбрать для инсталляции другой каталог (причем можно пользовательский, а не системный). В дальнейшем тексте предполагается, что RenderX XEP установлен в каталог по умолчанию. При работе XEP с большими (порядка сотни страниц) документами ему может не хватит оперативной памяти. В этом случае увеличьте объем памяти, отводимый для java-машины, добавив параметр в вызов java в командном файле /usr/local/RenderX/xep: "$JAVA_HOME/bin/java" -Xmx500000000 Задайте половину физического объема памяти сервера в байтах (в данном примере задано 500 мегабайт).

Скопируйте файлы arial*.ttf, cour*.ttf, times*.ttf, tahoma*.ttf, verdana*.ttf, pala*.ttf из ОС Windows 98/200x/XP, установленной на персональном компьютере (каталог C:\WINDOWS\FONTS) в каталог /usr/local/RenderX/XEP/fonts сервера. Отредактируйте конфигурационный файл /usr/local/RenderX/XEP/xep.xml: Найдите строку комментария Sample configuration for Windows TrueType fonts. Раскомментарьте следующие за ней текст между тэгами <font-group> и </font-group>. Удалите атрибут xml:base из тэга <font-group>.

Скопируйте docbook.xsl в pdf.xsl и отредактируйте файл pdf.xsl: замените html/chunk.xsl на fo/docbook.xsl добавьте параметры ]]> Запустите XSL-процессор: article.fo Making portrait pages on A4 paper (210mmx297mm) $ ]]>

Наберите команду: В результате должен образоваться файл article.pdf. Открыв его в браузере, вы увидите примерно следующее: Настройте внешний вид документов проводите согласно справочнику по параметрам XSL-FO. Очень подробно вопросы настройки рассматриваются в книге .

theDocBook Norman Walsh, Leonard Muellner. theXSL Bob Stayton. theXML Elliotte Rusty Harold. Dict Анатолий Белайчук.