Лучшие статьи журнала ╚Компьютеры+Программы╩

Здравствуйте, уважаемые читатели!

В этом выпуске рассылки публикуется статья, занявшая по результатам голосования третье место.

Александр ГРОМНИЦКИЙ,
ep_big@comizdat.com

Система написания структурированных документов

- Что с тобою, патрикий? Странный ты человек! Муж, наделенный крепостью в мышцах и разумом, осыпанный милостями благочестивого, а презираешь радости жизни. Другие имеют жен, потомство, приобрели имения, а ты тратишь средства на переписку книг, как будто они могут заменить человеку земные блага. Почему ты не хочешь быть таким, как все?
- В книгах и есть настоящая жизнь.
Антонин Ладинский

К хорошим программам обычно составляется хорошая документация. Более того, к действительно хорошим программам руководство начинает писаться еще до начала разработки самого ПО. Часто, выбирая из нескольких аналогичных вариантов, мы предпочитаем остановиться на более документированном проекте, а его плохо документированные аналоги обычно «висят» в неопределенном состоянии годами, в конечном итоге умирая, так по-настоящему и не родившись.

Конечно, бывают исключения, но связаны они, скорее, с отсутствием возможности хоть какого-то выбора, что и вынуждает несчастного пользователя руководствоваться пресловутым «методом тыка» и выуживать жалкие крохи информации, ныряя, словно рыба, в пучину конференций USENET.

Составляя документацию к своему ПО, разработчик может ограничиться объемными комментариями в исходных текстах и коротким README-файлом и (если это проект open source) выложить все исходные тексты в интернет. Таким безрассудным действием он только отпугнет большую часть потенциальных пользователей. Вплоть до появления более крупного README-файла, а в идеале — полного комплекта документации или, если хотите, помощи.

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

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

• plain text;
• HTML;
• XML;
• PostScript;
• PDF.

Все они общеизвестны и в комментариях не нуждаются. Закрытым же или специфическим для каждой платформы форматам (например, man-страницы в Unix) здесь внимания уделять не будем.

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

Пропагандируемый XML (в чистом виде) — по аналогии с собакой и в противоположность HTML — «знает, но сказать (читай: отобразить) не может».

В «лучших домах Парижа» хорошим тоном считается иметь отдельно структуру документа и его представление, а результат отображать в нескольких общечитаемых форматах. Беда сторонников метода грубой силы, вроде упомянутого XML, заключается в бесконечном определении собственных DTD (Document Type Definition) для овеществления смыслового содержания придуманных тегов и не менее захватывающая борьба с поддержанием их представления о собственном внешнем виде (например, используя XSLT).

Проблемы наподобие описанных могут быть разрешены введением стандарта на DTD и выделением оного в отдельный язык, как это было с HTML. Но, как мы знаем, этот вариант при всех его прелестях (в большинстве своем мнимых), нас не устраивает. Как же быть?

Использовать другое!

- А вчера тебя опять видели с этим агарянином. Неприлично!
- С Сулейманом?
- С Сулейманом
Антонин Ладинский

Стандартов написано множество. Различий между всеми ними, если отклонить булевы субъективные заметки о качестве, всего… нет, не два, а четыре — по типу использования. Их либо применяют, либо редко применяют, либо модифицируют (иногда значительно), а бывает (и, в принципе, не так уж и редко) — игнорируют.

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

Его имя — DocBook, что звучит немного банально, зато довольно уверенно. Уверенность достигается благодаря наличию «в портфеле» обширного числа сторонников почти всех крупных open-source-проектов.

История DocBook началась в далеком 1991 году — при совместной работе HaL Computer Systems и известного издательства O'Reilly & Associates. Первоначально он был задуман как средство для облегчения обмена Unix-документацией в формате troff. Построенный на определении DTD синтаксиса SGML, проект настолько лихо стал набирать популярность, что даже породил для собственной поддержки целую организацию Davenport Group (в 1994 году — когда вышла его версия 1.2.2). На развитие DocBook оказывали постоянное влияние Novell и Sun, под воздействием которых он продолжал интенсивно развиваться.

В январе 1997 г. вышла версия 3.0, но, несмотря на всё увеличивающуюся аудиторию пользователей, проект резко начал чахнуть — его многочисленных приверженцев охватила лихорадка XML. Возникла идея стандартизации XML-совместимой версии DocBook, но реальная совместимость появилась только четыре года спустя. На Davenport Group стали недовольно коситься спонсоры, явно желавшие прикрыть контору. В конце концов DocBook передали в руки OASIS — и в жарком июне 1998 года новая организация под немного пафосным названием «OASIS DocBook Technical Committee» начала свою плодотворную работу.

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

Тем не менее, часть приверженцев (например, «фанаты» проекта FreeBSD) не собирается отказываться от SGML. По сути, это вопрос больше религиозный, чем практически обоснованный, а подавляющее множество пользователей не замечает принципиальной разницы между SGML- и XML-вариантом, что свидетельствует о достижении фактически полной совместимости.

Старые версии DocBook (3.1, 4.1) в довольно жесткой форме не рекомендуются к употреблению. С DocBook XML 4.2 немного проще, так как до 4.0 официальных релизов вообще не было.

Еще в эру правления Davenport Group был выработан стиль наименования версий, пользуясь которым можно облегчить себе управление между ними. Дробные версии, такие как 4.1, имеют право вносить изменения в модель разметки, но не могут изменить ее обратную совместимость. Так, документ, соответствующий версии n.0, будет соответствовать и версии n.m. Целые версии, такие как 3.0, могут с чистой совестью изменять модель разметки, не глядя на совместимость. Такие релизы должны выходить с промежутком не менее чем в один год.

Ну, допустим…

- В чем же дело?
- Что тебе надо от этого врага христиан?
- Мы беседовали с ним о путешествиях. Сулейман хорошо знает греческий язык, любит Аристотеля. Он рассказывал мне о Дамаске и Иерусалиме. Даже об Индии. Это — путешественник, астроном, любитель красивых вещей.
Антонин Ладинский

DocBook — язык большой и многословный, что не позволяет в приемлемом объеме описать его на страницах журнала. Документы, написанные на DocBook, естественно, не читаются никакими браузерами, поэтому для распространения документации вам придется конвертироваться в любой из указанных выше форматов — плюс множество других (TeX, GNU Texinfo, etc), включая даже аудио.

Для понимания работы DocBook вам необходимы хотя бы минимальные знания SGML или XML (в зависимости от того, какая реализация для вас предпочтительнее). Автору больше нравится первая, так что примеры будут хоть и не слишком зависимы от нее, но написаны все же на SGML.

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

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

Есть смысл немного разобрать написанное:

• <! — индикатор, показывающий начало декларации SGML;
• DOCTYPE SGML — объявление типа документа;
• book — имя первого элемента, который появится в документе;
• PUBLIC "-//OASIS//DTD DocBook V4.2//EN" — формальный публичный идентификатор (Formal Public Identifier, FPI). Используется SGML-анализатором для поиска правильного DTD при обработке этого документа. Ключевое слово PUBLIC показывает анализатору SGML, как найти DTD в FPI;
• > — возвращение к документу.

Для нормальной работы с DocBook вам необходимо знать и уметь использовать понятие сущности (entity). Сущности позволяют присвоить некое имя части текста. Впоследствии анализатор SGML, если находит имя такой сущности, заменяет его на содержимое. C помощью такого механизма возможно включение одного размеченного файла в другой.

Сущности бывают двух видов: сущности общего вида (general entities) и параметризированные (parameter entities). Обе определяются в контексте SGML, но использование их существенно различается: последние могут использоваться только в пределах этого SGML-контекста, а первые — только в самом документе.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ <!ENTITY product.name "World Best Program"> <!ENTITY % some.one "Уилкса"> <!ENTITY % some.two "Виктории"> <!ENTITY % info "Земли &some.one и &some.two находятся рядом"> ]>

Здесь определено четыре сущности: одна общего вида и три — параметризированного.

Различия определения наблюдаются в присутствии символа % после !ENTITY у параметризированных сущностей. Как их использовать? Допустим, время от времени в вашем тексте мелькает название программного продукта, который вы, собственно, и описываете. Вы даете имя сущности общего вида — скажем, product.name. Тогда можете сразу написать, что:

<para>Наша программа &product.name — самая полезная в мире!

Сущности общего вида применяются также для написания разных зарезервированных символов в SGML — таких как <, который заменяется на <.

Наиболее весомый вклад entities вносят, когда используются для вставки содержимого из другого файла. Причем эти файлы, оформленные по всем правилам SGML, не должны содержать объявление DOCTYPE. Чтобы отличать такие сущности, объявление следует производить вместе с ключевым словом SYSTEM.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ <!ENTITY chapter.1 SYSTEM "chapter1.sgml"> <!ENTITY chapter.2 SYSTEM "chapter2.sgml"> ]> <book> ... &chapter.1; &chapter.2; ... </book>

SGML представляет довольно гибкий механизм для специальной обработки некоторых частей документа, иногда называемый «пометкой раздела».

<![ CDATA [ Данная секция документа содержит много разных символов, < < < > > > так что ее проще пометить как CDATA. &&&&& ]]>

CDATA — одно из ключевых слов, указывающих, как обработать секцию. CDATA — Character Data (символьные данные) дает анализатору понять, что здесь могут быть любые символы и что с ними не нужно делать ничего, кроме как считать их. Еще бывает RCDATA — Entity references and character data (ссылки на сущности и символьные данные), где все сущности (entities) действуют (то есть < никак не обрабатывается, а после &, как обычно, ожидается некая entity общего вида).

Известным трюком, демонстрирующим работу параметризированных сущностей является использование ключевых слов INCLUDE и IGNORE, означающих в помеченных разделах разрешение на включение и исключение текста соответственно. Предположим, вы решили создать документацию в электронном и «твердом» видах. Некоторая часть, высвечиваемая в электронной копии, не должна попасть в копию твердую.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ <!ENTITY % electronic.copy "INCLUDE"> ]]> ... <![ %electronic.copy [ Будет видно только в электронной копии. ]]>

Для печатной версии просто поменяйте ключевое слово INCLUDE на IGNORE.

Ну а DocBook?

Действительно, сам DocBook мы еще не рассматривали. Нехорошо получается. Но беда в том, что он, хоть и предельно элементарен, но велик — а, как уже выше говорилось, рассматривать его весь не имеет смысла. Поэтому сосредоточимся на общей картине.

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN"> <article> <articleinfo> <title>Пример документа типа «статья»</title> <author> <firstname>Имя</firstname> <surname>Фамилия</surname> </author> <copyright> <year>2003</year> <holder>Строка авторских прав</holder> </copyright> <abstract> <para>Содержание</para> </abstract> </articleinfo> <sect1> <title>Раздел 1</title> <para>Давным-давно...</para> <sect2> <title>Подраздел 1.1</title> <para>Вот совсем недавно...</para> </sect2> </sect1> </article>

Как вы уже заметили, в объявлении DOCTYPE есть article, которое и является у нас первым элементом. В статье информация организовывается, разбиваясь на элементы типа секций <sect1>, которые могут иметь подразделы <sect2>. Элемент <para> означает параграф. Название остальных элементов настолько очевидны, что говорят сами за себя.

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

Что, где и как

Ксифий смотрел на меня как на безумного:
- Все-таки он враг. Тебе лгут, а ты внимаешь подобным вещам...
Антонин Ладинский

Для преобразования DocBook в другие читаемые форматы вам понадобятся кое-какие инструменты. Для задач вывода в RTF, HTML и TeX наиболее популярен конвертер OpenJade (http://openjade.sourceforge.net/), использующий для преобразования List-подобный язык DSSSL (www.jclark.com/dsssl/) и стилевые таблицы DSSSL (http://sourceforge.net/projects/docbook). Это кроссплатформенная разработка — правда, пользователям Windows придется смириться с не очень привычным для них интерфейсом с командной строки.

Второе издание книги «DocBook: The Definitive Guide» от O'Reilly&Associates, подробно описывающее предмет, находится на www.docbook.org/tdg/en/. Хороший FAQ — на www.dpawson.co.uk/docbook/.

Технический комитет DocBook (OASIS DocBook Technical Committee) находится на www.oasis-open.org/docbook/.

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

Александр ГРОМНИЦКИЙ,
ep_big@comizdat.com

До следующего выпуска!
Елена Полонская, редактор "К+П"
www.comizdat.com

Перепечатка материалов этой рассылки разрешается только по согласованию с редакцией журнала "Компьютеры+Программы"