Мировое зло vs. XML в белых одеждах

Автор: Александр Прокудин
Опубликовано в журнале "Компьютерра" №6 от 15 февраля 2005 года.

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

Тенденции

Дабы не быть съеденным заживо, мотивирую свое мнение примером из реальной жизни. Документацию к крупному проекту пишет десять и более человек. Литературную и научную правку вносят еще четверо. Авторам и редакторам нужно:

Если не считать количества участников, задача типична для большинства компаний, выпускающих коробочный продукт. Более того, поскольку мы говорим о коробочном продукте, то подразумеваем наличие не только красивой печатной документации, но и удобной в использовании электронной документации. А это значит, что для минимизации усилий обе версии нужно изготавливать из одного и того же исходника. Эта методика подготовки документации так и называется: single source, то есть единый исходник.

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

Стоит ли говорить, что текстовые процессоры на все это неспособны? Нет, разумеется, можно, выдергивая из головы последние волосы, писать сценарии на VBA или OpenBasic, размечать текст диковинными стилями, пользоваться Visual Source Safe или вообще Documentum. Но все это приводит к невыносимой головной боли и преждевременному выходу на пенсию по состоянию здоровья.

Решений может быть несколько. Начну с того, которое у нас только набирает популярность, а на Западе уже стало нормой. Это использование DocBook/XML в связке с той или иной системой конкурирующих версий вроде CVS, SVN, Arch или VSS и XSLT-процессором. В свое время мне пришлось организовывать перетаскивание массива документации в шесть с лишним сотен страниц из документов OpenOffice.org Writer в DocBook/XML, так что делиться буду сугубо личным опытом, приобретенным за время работы в опенсорсном проекте ALT .

DocBook/XML

Итак, почему в проекте создания документации для решений на базе Sisyphus (Банк пакетов с ПО, поддерживаемый как оплачиваемыми сотрудниками ALT Linux, так и добровольцами, и служащий основой решений в равной степени для компании и сертифицируемых ей разработчиков) был выбран именно DocBook ? Когда требуется издавать одну и ту же документацию и в печатном, и в электронном виде, необходимо как можно больше абстрагироваться от конечного формата. В HTML нет ни разрывов страниц, ни колонтитулов (замену им, конечно, всегда можно придумать), ни много чего еще, что свойственно печатной документации. В свою очередь, у печатной документации есть свои ограничения, легко преодолеваемые при создании электронной версии.

Таким образом, идеальным вариантом является некий язык разметки, который позволяет логически разметить текст и встраиваемые объекты без особенностей форматирования, мешающих при сборке документации в другой формат. DocBook на тот момент оказался (и до сих пор остается) самым подходящим решением в силу следующих причин:

По сути, DocBook/XML является сильно упрощенной разновидностью громоздкого и неповоротливого SGML. Но и у него есть своя облегченная версия (www.docbook.org/specs/wd-docbook-simple-1.1CR2.html), состоящая из всего лишь сотни тегов. Расширить готовый DTD проще простого: достаточно написать новое описание, которое будет включать в себя ссылку на имеющееся. Таким образом можно добавить недостающие элементы. Останется лишь поправить стили преобразования так, чтобы они «понимали» ваши элементы.

Что касается модульности, тут преимущества налицо: автор «заливает» в CVS документацию в виде, скажем, десяти файлов плюс одного, их объединяющего (пользуясь терминологией Adobe FrameMaker — мастер-документа). Больше того, он может сказать, что четыре из десяти файлов он хочет еще «поколупать» и их пока можно только читать, а вот остальные можно править прямо сейчас. И пока автор доделывает работу, пара редакторов может разделить между собой первые шесть и вносить в них изменения. Причем благодаря системе хранения версий, и автор, и второй редактор всегда могут просмотреть только изменившиеся после правки первым редактором строки.

Первая же проблема, с которой три года назад столкнулись мы и с которой мигранты на XML сталкиваются до сих пор, — как получить красивую документацию в PostScript или PDF. Оба рассматривавшихся нами свободных решения, PassiveTeX и FOP, предполагали промежуточное преобразование в формат XSL-FO (eXtensible StyLesheets — Formatting Objects). Выбор был сделан в пользу первого: FOP в то время категорически отказывался нормально работать с текстами на русском, не говоря уж «русских» переносах. А вот PassiveTeX с русским работал без слишком сильного «допиливания», да и для переносов использовал знаменитые ТеХ-таблицы.

Проблема с получением красивых PDF для организаций, не обязанных пользоваться только свободными продуктами, решается элементарно — покупкой программного продукта с ласкающим русское ухо именем XEP (и его модуля для создания HTML-версии — HAXEP) (Это не шутка. Сходите на www.renderx.net и убедитесь сами. И не удивляйтесь, что в компании работают русские программисты. Название продуктам они придумывали в давно минувшую (к счастью) пору финансового кризиса). Работает эта дивная программа точно так же, как и FOP: делает из DocBook/XML документ в формате XSL-FO, а затем преобразовывает в PDF.

Словом, первая схема работы стала такой: исходные документы пишутся в DocBook, затем преобразовываются в XSL-FO, обрабатываются PassiveTeX и передаются pdflatex для печатания в PDF либо сразу преобразовываются из DocBook в HTML. Больше того, к HTML-версии был добавлен CSS-стиль, а CSS — заслуженно популярное средство индивидуализации облика документов.

К сожалению, вскоре выяснилось: для того чтобы текст в печать уходил красивым, нужно «допиливать» исходный код PassiveTeX, который владелец большого рашпиля из числа ALT Team метко назвал «ужасом, летящим на крыльях ночи», «в сравнении с его кишками кишки LaTeX — это нечто очень светлое и ровное». Словом, нет в жизни счастья.

От такой невеселой жизни пришлось искать вариант, который помог бы, не перенося всю накопленную массу документации в LaTeX, получать красивые PDF. Так были найдены два проекта со схожими названиями: db2latex и dblatex. Второй был признан совершенно непригодным, а первый прижился и используется до сих пор, поскольку позволяет получать печатную документацию практически безупречного качества, хотя и не без этапа доверстки. К сожалению, вынужден отметить, что скорость реагирования авторов оригинальной разработки на присылаемые патчи и конструктивную критику оставляет желать лучшего.

Использование DocBook/XML на полную катушку вскрыло еще одну проблему: отсутствие хороших XML-редакторов именно для написания текстов. Ведь одно дело, когда вам нужно поправить пятикилобайтный конфиг с XML-разметкой, и совсем другое — написать документ килобайт так на 90, не отвлекаясь на особенности разметки. И даже когда количество используемых тегов не превышает двадцати, хочется удобства. Для авторов, сталкивающихся с DocBook впервые, это особенно актуально. Поэтому за время работы в ALT я «переспал» практически со всеми свободными XML-редакторами, а в нерабочее время — и с несвободными тоже.

Работают все они по одному и тому же принципу: слева висит дерево документа, по которому можно быстро перемещаться между отдельными его частями. В основном, центральном окне находится пространство работы с собственно текстом, где границы каждого тега так или иначе обведены рамочкой, а имена тегов показаны как можно ненавязчивее. Справа висит панель с подсказкой возможных в данном контексте тегов. Полного «взвизгового» режима вы не дождетесь — такова природа XML. В лучшем случае вы получите WYSIWYM — как в LyX. Среди всего множества подобных разработок отмечу кроссплатформный Serna отечественных разработчиков из Syntext (рис. 1).

Надо сказать, что на практике лучшей связкой для меня все равно оказался текстовый редактор, умеющий загружать DTD по объявлению в начале документа и сообщающий об ошибках в разметке, и окно браузера с открытым в нем The Definitive DocBook Guide на тот случай, если вдруг что-то забуду. Сейчас, когда я написанием свободной документации занимаюсь только в редкие часы свободного времени, — это Kate (рис. 2), умеющий к тому же автоматически дописывать длинные ранее вводившиеся слова, и Firefox. У Kate в отличии от коммерческих программ нет отдельной менюшки, через которую можно вызвать функцию преобразования исходного документа в другие форматы, зато есть консоль, из памяти которой всегда можно легко извлечь ранее введенную команду для XSLT-процессора. А еще можно «свернуть» в строку неиспользуемую часть дерева документа, что заметно экономит время.

Из сравнительно недавних разработок стоит упомянуть Vex — IDE для написания документов с XML-разметкой, очень сурово завязанную на коллективную работу при помощи CVS и основанную на коде любимого программистами IBM средства разработки Eclipse.

Писать в DocBook/XML можно даже при помощи OpenOffice.org Writer, только делать это надо по специальному шаблону (xml.openoffice.org/xmerge/docbook). К сожалению, отсутствие качественного стиля обратного преобразования из DocBook в формат SXW пока что мешает сделать Writer основным средством написания текстов в DocBook и снизить порог вхождения для техписов, которые задействованы в вашем проекте эпизодически.

При таком раскладе использование DocBook/XML становится вполне оправданным. Ведь даже если вы не можете перевести своих техписов на GNU/Linux и свободную инфраструктуру сборки документации, вы всегда можете посадить их на виндовые продукты, частично использовать эту инфраструктуру, и получать из единого исходного документа и HTML, и HTML Help, и PDF. XSLT-процессор не умеет сразу создавать конечный файл в формате CHM, но он создает файл проекта и индексный файл, на который затем остается лишь натравить HTML Workshop или любую другую программу для создания CHM. При очень сильном желании можно озаботиться запуском HTML Workshop при помощи wine (что пока ни у кого не получилось из-за завязки программы на ActiveX), а полученную документацию просматривать в xCHM или gnoCHM (рис. 3) — уже «родных» юниксовых программах.

В юниксах XML уже несколько лет используется в качестве исходного формата для массовой электронной документации: в программах на основе KDE и GNOME. Разработчики поступили мудро и, не изобретая форматный велосипед, просто взяли DocBook 4.1 и приделали к нему генераторы HTML-документов с поиском, закладками и прочим. Получились соответственно Yelp и KHelpBrowser (рис. 4).

Пользователи Windows смогут проникнуться аналогичной «инновацией» Microsoft, только установив Longhorn. Из лежащих в Сети скриншотов новой электронной справочной системы явствует, что DocBook и в Редмонд пробрался.

Впрочем, создатели KHelpBrowser пошли еще дальше: они написали утилиты xml2pot и pot2xml, благодаря которым документацию можно держать разбитой на фрагменты в обычном ресурсном файле PO для переводов. Как только оригинал меняется, в PO-файл перевода документации вписывается новый текст, а устаревший перевод помечается как нечеткий (fuzzy). Так что поиск изменений превращается в переход между автоматически определяемыми любым PO-редактором (Каковые есть хоть под Linux, хоть под Windows: KBabel, poEdit, gtranslator) «нечеткими» строками, а само создание и поддержание в актуальном состоянии многоязычной документации с технической точки зрения становится сплошным удовольствием.

Соперники DocBook

У DocBook по-прежнему есть два соперника. Первый — это TEI, еще одно наследие SGML. TEI изначально ориентирован на гибкую работу с литературным текстом, а потому пользуется большой популярностью у библиотек при оцифровывании архивов. Для написания документации он используется сравнительно нечасто.

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

Проблема заключается в том, что даже при использовании изумительного полувизуального редактора LyX остается проблема коммуникации с внешним миром. Но и здесь не все так плохо. Специалисты из питерской компании Etersoft предлагают решение, основанное на LyX как инструменте создания документации в соответствии с нормативами ГОСТ и PDF как универсальном формате документооборота. В некоторых случаях менеджерский состав по старой памяти может воспротивиться использованию Adobe Reader вместо привычного Word, но это легко решаемый вопрос.

Adobe FrameMaker

Этот продукт, в общем-то, в особых представлениях не нуждается. Программа совершенно заслуженно пользуется популярностью у технических писателей и их руководителей, поскольку ей можно спокойно доверить автоматическую верстку очень больших пакетов очень важной документации. Больше того, в России есть сообщество, поддерживающее средства исправления исторически сложившейся нелюбви FM ко всему русскому и кириллическому. Благодаря ему, в частности, во FrameMaker можно проверять орфографию текстов на русском языке, а с некоторых пор даже вставлять «мягкие» и «жесткие» переносы. Документы формата HTML Help получаются превосходно, поскольку RoboHelp прекрасно интегрируется с FrameMaker.

Кстати, у Adobe FrameMaker понемногу вырисовывается конкурент среди программ с открытым исходным кодом — Passepartout, пока еще молодая программа для автоматической верстки из документов с XML-разметкой. Принцип работы очень прост: вы указываете программе такой документ в качестве источника, а потом указываете, каким XSL-стилем его обработать. Любые изменения в исходном документе немедленно отображаются в окне Passepartout. При должном общественном внимании из проекта может вырасти очень мощный программный продукт для техписов и не только.

В мире дорогого закрытого софта у FrameMaker тоже есть конкурент: Epic Editor и линейка сопутствующих продуктов, прекрасно подходящих для работы с документами в XML-разметке.

Исключения

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

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

Заменить Word на Writer в этих случаях пока не удается: помимо того что при сохранении в DOC может поползти разметка, в «Райтере» нельзя делать гостовские рамочки, столь любимые руководством крупных госзаказчиков и специалистами по нормоконтролю. А клиентов, как и ГОСТы 19/34, принято любить и ценить.

Впрочем, и тут есть подвижки в сторону избавления от ига DOC. Например, Sun Microsystems всю свою документацию и презентационные материалы распространяет либо в PDF, либо в SXW/SXC/SXI — форматах StarOffice и OpenOffice.org. Кроме того, на основе формата ОО.о в OASIS создан стандартный формат электронных документов, который называется OpenDocument, а значит, государственные организации во всей Европе будут в принудительном порядке переводиться на этот формат, а компании, работающие с ними, будут вынуждены предоставлять электронную документацию именно в нем.

После комплиментов в адрес DocBook/XML наверняка возникнет вопрос, как можно убедиться в преимуществах решений на его основе. Как ни странно, в Интернете пока нет ресурсов, где подробно описываются все тонкости использования DocBook. Неплохое введение есть на страничке docs.altlinux.ru. А конкретные вопросы можно обсудить в любой из трех профессиональных веб-конференций Рунета: в форуме (www.forum.philosoft.ru) на сайте компании «Философт» и двух узкоспециальных персональных «песочницах» участников первого форума. В первой (techwriter.rarus.ru/_conf) обычно обсуждаются тонкости использования Adobe FrameMaker, а во второй(ergd.ru/forum) — создание проектной документации в соответствии с ГОСТами (и не только).