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

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

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



charset=ISO-8859-1»>





of HOWTOs added to Samba documentation over the years.

Копнув еще глубже, обнаруживаем, что 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 существует с 1991 года и к сегодняшнему дню ...







Наблюдательный пользователь ...



...







Хорошая новость: ...









...



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

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

Для работы с 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.

Не в последнюю очередь источником проблем PDF является компания Adobe — трудности с поддержкой русского языка возникают чуть ли не во всех ее продуктах: и в Photoshop, и во FrameMaker, и в Acrobat. Видимо, среди программистов в Adobe еще нет выходцев из бывшего СССР. Вот что пишет компания по поводу Adobe Acrobat версии 6: «При создании PDF из HTML-файлов текст, набранный кириллическими шрифтами, заменяется неправильными символами или пустотами». Иными словами, не работает — и не должно!

В итоге мы пришли к выводу, что единственный простой и надежно работающий вариант генерации PDF на русском языке — это Acrobat Distiller, который умеет включать используемые шрифты в создаваемый документ, что гарантирует его прочтение на любом компьютере, а не только на том, что оснащен русской версией Windows.

Для технического писателя

Традиционно под документацией в первую очередь понимался напечатанный документ или книга. Но сегодня документация в большинстве случаев требуется и в печатном, и в электронном виде. Если у вас уже есть документ, сверстанный для печати, то самый простой (и универсальный) способ сделать его электронный вариант — воспользоваться Adobe Acrobat Distiller. Вы получите PDF, который можно записать на компакт-диск или выложить на сайт. Однако PDF — не родной для Internet формат. Ваши документы не станут органической частью сайта и будут раздражать пользователя длительной загрузкой, к ним не удастся привязать стандартное оформление сайта (шапки, панели, сервисы), в них затруднено использование ссылок и поиск средствами сайта.

Еще одно дешевое решение — выполнить экспорт в HTML, например, из Microsoft Word. С точки зрения интеграции с Web-сайтом этот вариант ненамного лучше PDF — такие документы также будут выбиваться из общего стиля сайта. Формально это, конечно, будет HTML, но по существу — нет, ведь даже сменить шрифт или увеличить размер символов при просмотре в браузере пользователь не сможет: все жестко прописано в сгенерированном тексте.

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

Кроме того, техническому писателю необходим сервис: автоматическая нумерация разделов, таблиц, рисунков, автоматическое формирование оглавления, перечня рисунков, алфавитного указателя. Со всеми этими задачами DocBook справляется.

Для коллективной работы

Если авторы работают с Word, то их документы содержат и контент (собственно текст), и дизайн (шрифты, оформление абзацев, страниц и т.д.). Поэтому дальше идет трудоемкая ручная работа: редактор собирает фрагменты и приводит верстку в соответствие со стилем, заданным дизайнером (теоретически в этом могли бы помочь собственный механизм стилей Word, но на практике он работает не очень хорошо.)

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

Как в этой же ситуации строится работа через DocBook? Редактор намечает структуру будущего документа — делит его на главы или более мелкие разделы. Для каждого раздела редактор создает отдельный файл DocBook, содержащий только название раздела. Редактор раздает файлы авторам для работы над контентом. Дизайнер разрабатывает файл CSS, определяя в нем стили для оформления регулярного текста, заголовков, ссылок, таблиц, рисунков и т.д. Редактор создает головной файл документа, содержащий ссылки на разделы. Выходной документ создается из набранных фрагментов автоматически.

Авторам не обязательно ждать, пока соберется общий документ, — они вполне могут запускать DocBook на своем фрагменте и смотреть, как он будет выглядеть в отформатированном виде. После такой предварительной отладки редактор может быть уверен, что получил от автора синтаксически правильный документ DocBook.

Поскольку весь документ разбит на составные части, которые к тому же являются текстовыми файлами, такая организация работы великолепно ложится на систему контроля версий (например, RCS или CVS). Снова вернемся к ситуации, когда в документ надо внести небольшую правку. Последовательность действий будет следующей. Автор достает из системы контроля версий нужный фрагмент документа, правит его, автономно просматривает и помещает исправленный вариант обратно в систему контроля версий. Редактор просматривает новый текст, при необходимости корректирует, но в отличие от работы с Word его заботит только контент. Автоматически генерируется выходной документ.

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

Контент, дизайн и структура

Единственное, что нас не устроило в работе с DocBook, — это «хвосты» SGML, которые появились в головном файле для организации ссылок на разделы документа. Во-первых, каждый файл должен быть упомянут дважды (один раз в определении, второй в размещении); но там, где дублирование, появляются ошибки. Во-вторых, работа со сложными структурами организована неадекватно. В рассмотренном примере всего два фрагмента, реальные же документы на программные продукты могут состоять из сотен фрагментов при значительной глубине вложенности разделов. Возникает естественное желание сделать структуру более наглядной. Но как нагляднее всего отразить иерархическую структуру, каковой является документ DocBook? Очевидно, иерархией каталогов.

Поэтому мы реализовали следующую схему работы с разветвленными документами DocBook. Под раздел любого уровня создается отдельный каталог. Содержимое раздела помещается в XML-файл, лежащий в этом каталоге, а для вложенных подразделов создаются свои подкаталоги. Сборка фрагментов осуществляется автоматически несложной программой, написанной на shell и XSLT. Правильный порядок следования разделов достигается при помощи явного атрибута «nr» в тэгах . SGML-декларации становятся ненужными.

Последнее представляется важным с точки зрения не столько технологической (в конце концов, с дублированием имен разделов можно было бы справиться), сколько концептуальной. Если необходимость разделения контента и дизайна — это более-менее общее место, то мы пошли дальше и добились разделения контента, дизайна и структуры.

Что это означает на практике? Абстрагирование вышележащих разделов от нижележащих и возможность легкого изменения структуры. Раздел верхнего уровня «не знает», какие подразделы окажутся в нем в результате эволюции документа: какие подкаталоги будут, те и включатся. А если у редактора возникла идея перенести какой-то подраздел из одной части документа в другую, переместить его выше или ниже по иерархии, то это делается с помощью проводника Windows.

Тотальное документирование

Стоит ли вашей компании внедрять DocBook? Если речь идет об автоматизации труда одного человека — технического писателя, то, пожалуй, нет: проще работать по старинке. Но если компания или организация стремится к прозрачности своих бизнес-процессов, то написание документации становится уделом многих. В основе современных методов контроля качества лежит правило «напиши, что делаешь, делай как написал». Значительная часть персонала, вплоть до менеджеров нижнего звена и даже рядовых исполнителей, участвует в документировании процессов управления. К тому же документирование бизнес-процессов — это не то, что можно один раз поручить внешним консультантам и после этого навсегда зафиксировать. Бизнес-процессы постоянно меняются, что должно отражаться в документации. То есть мы приходим к уже описанной ситуации «много авторов — один редактор».

XML-стратегия

DocBook основывается на технологиях XML. Надо ли бояться, если эти технологии для вас внове? По нашему мнению, XML заслуживает того, чтобы каждой ИТ-компании сформировать по отношению к нему собственную стратегию использования. XML — не дань моде, хотя и не палочка-выручалочка. Это эффективное решение для широкого круга задач, которые до сих пор плохо поддавались автоматизации. Компьютеры давно уже приспособили к хранению и обработке, с одной стороны, жестко структурированных и объемных данных, а с другой — слабоструктурированной информации, такой как текстовые документы. Сила же XML состоит в том, что он позволяет эффективно организовывать и обрабатывать квазиструктурированную информацию: спецификации и API; требования заказчика и сценарии использования; тестовые данные и сценарии; часто задаваемые вопросы; учебные курсы с лекциями, примерами и тестами. Подобная информация, как правило, представляет собой коллекцию объектов с одинаковой структурой верхнего уровня и текстовыми описаниями на нижних уровнях. В отличие от представления такой информации в виде текста, XML позволяет отразить структуру. С другой стороны, по сравнению с базами данных XML обладает гораздо большей гибкостью, при том что объемы информации здесь невелики и мощь СУБД не требуется. Есть масса примеров успешного использования DocBook в подобных задачах. Например, учебная лекция представляется в виде одного XML-файла, из которого автоматически формируются: слайды для лектора; раздаточные материалы для студентов; тестовые данные для лабораторной работы; экзаменационные задачи, вопросы и тесты.

DocBook умеет формировать выходные документы не только в различных форматах, но и с различным содержанием, в частности, в зависимости от читателя (лектор/студент, заказчик/исполнитель).

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

Анатолий Белайчук (bell@b-k.ru), Мария Николаева (mmm@b-k.ru), Надежда Матвеева (matveeva@b-k.ru), Станислав Фридкин (stas@b-k.ru) — сотрудники компании «Бизнес-Консоль» (Москва).

Стандарт DocBook

Тэги DocBook стандартизованы на уровне спецификаций, выпускаемых комитетом при консорциуме OASIS (Organization for the Advancement of Structured Information Standards, www.oasis-open.org), в который входят представители компаний Hewlett-Packard, IBM и Sun Microsystems. По состоянию на март 2005 года последней официальной версией спецификации является версия 4.2, датированная июлем 2002 года, номер последней рабочей версии — 4.4. Эти версии существуют в виде XML и SGML. В версии 5.0 планируется перейти к единой схеме, совместимой как с SGML, так и с XML.

Материальное воплощение DocBook — это XML-схемы (DTD) и скрипты (DSSSL, XSLT). Они распространяются свободно: их разрешается использовать с любыми целями, модифицировать и тиражировать без ограничений и специального разрешения. Единственное, что запрещается в соответствии с духом сообщества Open Source — это ограничить других в свободном использовании и распространении DocBook или его модификаций.

Стандартом в популярном изложении DocBook служат руководства [1, 2], где произведена «селекция»: исходные примерно 400 тэгов сведены к 100 наиболее употребительным (скорее всего и это много больше, чем реально понадобится). Для настройки XSLT-инструментария и параметров, влияющих на вид выходных документов, вам понадобится руководство [3] и справочник [4].

Литература
  1. Norman Walsh, Leonard Muellner. DocBook: The Definitive Guide (www.docbook.org).
  2. Norman Walsh. Simplified DocBook: The Definitive Guide (www.docbook.org).
  3. Bob Stayton. DocBook XSL: The Complete Guide (www.sagehill.net/docbookxsl).
  4. Norman Walsh, Bob Stayton, Jirka Kosek DocBook XSL Stylesheet Reference Documentation (docbook.sourceforge.net/release/xsl/ current/doc/reference.html).

DocBook Website

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

В ходе генерации к каждой странице автоматически подверстывается панель с иерархическим оглавлением сайта, пункты которого можно сворачивать и разворачивать. Также автоматически в оглавлении выделяются новые и измененные страницы. Примечательно, что ссылки между страницами сайта оформляются не при помощи привычных , а при помощи тэга docbook . Это гарантирует, что все внутренние ссылки на результирующем сайте будут корректными.

Основное достоинство этой технологии, как и DocBook в целом, — последовательное отделение контента от дизайна. Скажем, сайты www.docbook.org, www.docbook.ru, сделанные по этой технологии, выглядят по-академически строго. Но, воспользовавшись стандартными приемами настройки DocBook, можно радикально менять дизайн и верстку своего сайта, абсолютно не затрагивая при этом его контент.