Подготовка технической документации с использованием asciidoc и DocBook

Это мой конспект для выступления на семинаре, проводившемся нашей LUG. См. также презентацию к докладу.

Глава 1. Актуальность, цели и задачи

Вобще говоря, разработка технической документации — это достаточно обширная область. Техническая документация, по идее, прилагается чуть ли не ко всему подряд — инструкция к чайнику, проектная документация к мосту, мануал к программе. Конечно, в разных случаях аудитория у документов разная, разные и цели подготовки документации, а потому используются разные подходы. Я буду говорить в основном о подготовке документации к программным продуктам, хотя практически всё это применимо и к разработке других видов документации (хотя, вероятно, предлагаемой методики недостаточно).

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

• Полная документация к большому продукту будет большой. Поэтому необходимо обеспечить автору документации простые и удобные средства для её подготовки, стараться не тратить время автора на посторонние вещи типа оформления этой документации или тонкостей xml-разметки;
• Пользователи у продукта, возможно, будут разные, а потому документацию необходимо предоставлять в разных форматах; самые популярные форматы — PDF, HTML и CHM;
• Так как пользователи разные, разной должна быть комплектация документации. В одних случаях нужно только руководство пользователя, в других — только руководство программиста, в третьих — и то, и другое.

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

Глава 2. Обзор технологий

Я начну с краткого обзора технологий, которые применяются для подготовки технической документации. Наиболее известны следующие технологии:

• MS Word и подобные системы;

• Системы «единого источника»:

  • Help&Manual и аналоги;
  • DocBook;
  • DITA;
  • и другие.

Рассмотрим некоторые из этих технологий несколько подробнее.

Глава 3. Help&Manual

Главным плюсом этой системы часто является то, что она уже внедрена и работает. Также несомненный плюс — это система единого источника, т.е. из одного текста можно получить документ в разных форматах. Особенность этой программы и аналогов: это WISIWYG-системы. Насчёт того, является ли эта особенность плюсом или минусом, по сей день не утихают споры. Плюс WISIWYG-технологий очевиден, он заложен в названии: можно сразу видеть, как будет выглядеть текст в результате. К минусам WISIWYG относят следующие пункты:

• Есть такое высказывание: если система предоставляет возможность что-нибудь настраивать, она, фактически, заставляет вас это настраивать. В данном случае это относится к тому, что автор тратит время не только на написание текста, но и на его оформление, хотя это, по идее, не его задача.
• Такие системы склонны порождать совершенно дикую и нечитаемую разметку при конвертировании в HTML, LaTeX и другие подобные форматы. Например, легко можно получить разметку наподобие: разметка. Это сказывается, как только появляется необходимость поправить такую разметку «руками».
• При работе в таких системах люди склонны использовать не логическую, а физическую разметку (например, помечать кусок текста жирным шрифтом, вместо того чтобы отмечать этот текст как заголовок). Что интересно, большинство таких систем предоставляют возможность использования логической разметки, иногда даже удобную, но по каким-то психологическим соображениям люди не склонны её использовать. Это приводит к проблемам при изменении общего стиля оформления документа, а также зачастую при конвертировании в другие форматы.

В связи с последним пунктом можно упомянуть системы с похожим девизом — WISIWYM (What You See Is What You Mind). Таких систем значительно меньше. К ним относится, например, LyX (http://www.lyx.org). Такие системы вобще не позволяют использовать физическую разметку. LyX, например, не позволит вам поставить два пробела или два разрыва строки подряд.

Известные минусы H&M и аналогов:

• Закрытый бинарный формат файлов; впрочем, это исправляется в новой версии H&M, где используется XML-формат;
• Следствие: для просмотра и редактирования нужна сама программа H& M;
• Все эти системы платные;
• Нет средств для управления версиями документации;
• Нет средств для обеспечения одновременной работы нескольких человек над одним документом.

Наш отдел документации, видимо, сравнительно небольшой. Важнее, на самом деле, что над одним документом у нас работает 1-2 человека - писатель и переводчик. Поэтому пока что отсутствие средств для управления версиями нам не слишком мешает.

Глава 4. DocBook

DocBook — это формат для ведения технической документации, основанный на XML. Разработка DocBook началась в 1991 году и, в разное время, развивался и поддерживался этот формат различными организациями:

• 1991—1994: HaL Computer Systems и O’Reilly & Associates (+ большое влияние Novell и Digital);
• 1994—1998: Davenport Group (+ большое влияние Novell и Sun);
• 1998—2007: OASIS. DocBook XML v4.5;
• 2 Aug 2008: OASIS. DocBook XML v5.0.

Раньше поддерживалась версия DocBook, основанная на SGML вместо XML (DocBook/SGML). SGML более «дружелюбен», более приспособлен к написанию человеком. Например, некоторые теги можно не закрывать, некоторые можно даже и не открывать. Это свойство досталось в наследство от SGML в HTML. Если в HTML-файле написать

Привет мир! <a href=http://site.com/>site.com</a>

(это полное содержимое файла), то браузер обязан интерпретировать это так же, как код

<html>
<header></header>
<body>
<p>Привет мир! <a href="http://site.com/">site.com</a></p>
</body>
</html>

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

Так что сейчас DocBook/SGML не поддерживается, поддерживается только DocBook/XML.

К плюсам этой технологии можно отнести:

• Не только открытый, но и стандартный формат, широко используемый как в OpenSource, так и в коммерческих компаниях;
• Существующие инструменты позволяют преобразовывать DocBook во все распространённые форматы (HTML, CHM, PDF итп);
• За счёт открытости и стандартности возможно реализовать преобразование в любой другой формат;
• Формат очень полный; в спецификации предусмотрены, например, специальные теги для сочетаний клавиш, для пунктов меню, и т.п;
• Формат можно расширять, дописывая собственные DTD;
• Это XML, а для работы с XML существует огромное количество инструментов и технологий;
• Т.к. исходные файлы текстовые, их можно держать под управлением системы контроля версий.

К минусам я бы отнёс:

• Высокий порог вхождения; нужно знать XML и саму спецификацию DocBook;
• Нетривиальная настройка вывода в HTML, PDF и т.п; Например, для вывода в PDF используется либо промежуточный вывод в TeX (так что для настройки нужно знать TeX), либо промежуточный вывод в XSL-FO (так что для настройки нужно знать XSL-FO);
• Системы контроля версий не так уж хорошо приспособлены к хранению XML-файлов.

Менее очевидным минусом является малое количество WISYWIG-программ для редактирования DocBook (но они есть, из бесплантых — Serna, разрабатываемая нашими соотечественниками).

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

Глава 5. DITA

Некоторыми (особенно в США) формат DocBook рассматривается как устаревающий. На смену ему приходит технология DITA. Это также формат, основанный на XML. Однако базовый формат определяет только основные теги, которые используются в любом документе. Все более специфичные теги определяются в так называемых специализациях DITA с помощью деклараций DTD. Существует несколько стандартных специализаций. Предполагается, что каждый пишет специализацию для своих нужд.

DITA содержит следующие нетривиальные идеи:

1. Текст пишется во многих небольших файлах, называемых топиками (topics). Каждый топик — это логически завершённый кусок документа.
2. Эти топики объединяются в выходной документ согласно содержимому других файлов — карт документа. Таким образом, получается, что текст отделён от структуры документации, текст и структуру можно менять независимо.
3. Каждый топик имеет определённый тип (doctype в смысле DTD), и структура топика определяется его типом. Стандартные типы — Задача, Концепция и Справочник. Например, топик типа Задача описывает последовательность шагов, необходимых для выполнения задачи. Топик типа Справочник содержит перечень элементов и их описаний, и т.д. Благодаря специализации всегда можно добавить свои типы топиков.

Плюсы:

• БОльшая, даже по сравнению с DocBook, гибкость формата;
• И все плюсы DocBook.

Минусы:

• По сравнению с DITA Docbook рассматривается как формат для чайников; Как минимум, здесь надо знать не только XML, а ещё и DTD;
• Т.к. формат ещё относительно новый, он пока слабее поддерживается;
• Тот же минус, что у DocBook: не лучшая поддержка XML со стороны систем контроля версий;
• Тот же минус, что у DocBook: сложность настройки вывода в PDF, по тем же причинам.

Про бесплатные WISIWYG-редакторы для DITA я ещё вобще не слышал.

Глава 6. Wiki-подобные разметки

Чтобы не писать в XML, широко используются различные Wiki-подобные разметки. Их очень много. Практически каждый wiki-движок предлагает свой язык разметки. Наиболее известны разметки MediaWiki (используется википедией) и dokuwiki.

Не все wiki-разметки поддерживают все средства форматирования, многие ограничены. Разметка MediaWiki поддерживает практически любое форматирование, но выглядит такая разметка страшновато. Dokuwiki выглядит более читаемо, но не поддерживает некоторое сложное форматирование.

Среди таких разметок известна ещё разметка Asciidoc. asciidoc - это скрипт на python, преобразующий соответствующую разметку в несколько выходных форматов. Есть возможность определить «бэкенды» для вывода в какие-нибудь ещё форматы. Достаточно хорошо поддерживаются выходные форматы HTML и DocBook. DocBook, в свою очередь, можно преобразовать практически во что угодно.

Существует программа (и библиотека) pandoc, предназначенная для конвертации различных форматов разметки. Например, с помощью этой программы можно преобразовать RST в Markdown, HTML или MediaWiki, или HTML в Markdown, и т.п. Эта библиотека достаточно гибкая, к ней можно писать фильтры — readers и writers. Я поддерживаю reader и writer для Asciidoc.

Плюсы такой технологии:

• Меньший порог вхождения, чем у XML-технологий;
• Системы контроля версий лучше всего работают как раз с plain text файлами;
• При использовании DocBook в качестве промежуточного формата получаем все плюсы технологии DocBook;
• В принципе, можно использовать DITA вместо DocBook в качестве промежуточного формата;
• За счёт наличия конвертеров всегда есть возможность уйти с этой технологии на какую-то другую.

Минусы:

• Порог вхождения всё-таки есть, хоть и небольшой;
• Из-за использования DocBook в качестве промежуточного формата получаем минус DocBook — сложность настройки вывода в PDF.

Глава 7. Применение для совместной работы

В основном здесь рассматривается использование web-интерфейса для работы с документами. Однако надо заметить, что это, не единственный вариант. Как минимум не стоит забывать про возможность использования систем контроля версий для совместной работы над документами.

Сначала я стал рассматривать возможность использования уже имеющейся веб-платформы — Confluence. Её, в принципе, можно использовать для разработки документации, но:

• Своеобразная разметка; это тоже wiki-разметка, но уникальная, никто кроме confluence её не поддерживает;
• Слабая поддержка импорта: практически есть возможность только импортировать doc-файлы;
• Слабая поддержка экспорта: confluence может экспортировать pdf, но так, что этот вариант не многим лучше распечатки веб-страницы на pdf-принтере; другие форматы вывода не поддерживаются;
• Сами тексты хранятся в БД, и в случае, если придётся переходить на другую технологию, тексты придётся как-то нетривиально добывать из БД.

Я давно использую Asciidoc, поэтому стал искать wiki-движки, которые бы поддерживали asciidoc. Как оказалось, среди огромного количества вики-движков только единицы поддерживают больше одного формата разметки. Единственный движок, поддерживающий Asciidoc — это Gitit, и как раз за счёт использования библиотеки pandoc. Кроме того, Gitit хранит тексты не в БД, а в текстовых файлах. Для контроля версий может использоваться одна из нескольких систем контроля версий (Git, Mercurial, Darcs). Так что если открыть доступ к этому репозиторию по сети, то получаем возможность редактирования содержимого вики с локального компьютера, любимым текстовым редактором, без веб-форм и вообще без соединения по сети (сеть нужна только чтобы взять содержимое и положить его обратно).

Gitit использует для обеспечения совместного редактирования достаточно простую модель. Предположим, один человек (A) начал редактировать страницу, затем (не дожидаясь пока A закончит) её начал редактировать Б. В таком случае, если изменения, внесённые двумя людьми, не пересекаются (например, они редактировали разные части страницы), будут применены все изменения. Иначе тому, кто закончит последним, будет предложено разрешить конфликты вручную.

Системы контроля версий используют примерно ту же модель, но могут обеспечивать бОльшую гибкость: см., например, git merge vs git rebase.

Глава 8. Об импорте и экспорте

Собственно, об экспорте я кратко уже упомянул. Программа pandoc позволяет конвертировать документы в разметке asciidoc в несколько распространённых форматов, включая docbook. В свою очередь, docbook можно сконвертировать во что угодно, даже в xml-формат последней версии H&M.

В случае необходимости можно преобразовать имеющиеся документы в формат asciidoc. В случае с исходными документами в формате H&M используемой, 4й версии, для этого придётся:

• Конвертировать исходный hmx файл в xml-формат новой версии H&M, используя конвертер, поставляемый с этой новой версией;
• С помощью небольшого скрипта и XSL-таблицы преобразовать полученный набор xml-файлов в один xml-файл docbook;
• С помощью ещё одной XSL-таблицы преобразовать docbook в asciidoc.

При этом возникают мелкие недочёты, связанные с особенностями работы H&M. Например, в его xml-файлах встречается разметка вида:

слово слово<strong> выделено </strong>текст...

или даже

слово <strong></strong> дальше текст...

Такая разметка, конечно, превращается в не вполне корректную asciidoc-разметку. Но это, вообще говоря, мелочи, и исправляется "поиском и заменой" в текстовом редакторе.

Глава 9. Улучшение поддержки DocBook

Для обеспечения более полной поддержки DocBook я определил в своём конфигурационном файле Asciidoc дополнительные макросы:

• icon:image.png[] для вставки иконок;
• button:button.png[Текст кнопки] для упоминаний кнопок;
• label:[Текст] для заголовков элементов управления;
• screenshot::screen.png[] для больших скриншотов.

Глава 10. Настройка вывода в PDF

Существует несколько способов преобразовать DocBook в PDF. Наиболее распространены два:

• С использованием XSL-FO в качестве промежуточного формата;
• С использованием LaTeX в качестве промежуточного формата.

XSL-FO — это ещё один XML-формат для представления форматированного текста. В отличие от DocBook, этот формат ориентирован на низкоуровневую физическую разметку. Преобразовать DocBook в XSL-FO несложно, для этого есть свободно доступные XSL-таблицы. Преобразованием XSL-FO в PDF занимаются специальные программы, называемые XSL-FO Processors. Их существует несколько:

• Apache FOP (бесплатный, но не поддерживает некоторых возможностей и имеет некоторые сложности с настройкой русскоязычного вывода);
• JadeTeX (специальная версия TeX, настроенная так, что понимает xml на входе);
• PassiveTeX (что-то из той же серии);
• XEP (коммерческий продукт, полностью функциональный, но опять же есть сложности с русским языком).

Собственно, различные сложности с русским языком есть у всех этих вариантов (они всегда решаемы, но это требует времени). Разработка JadeTeX и PassiveTeX, к тому же, на данный момент заморожена.

Другой вариант преобразования — использовать в качестве промежуточного формата TeX. Для преобразования DocBook в TeX используется программа dblatex, представляющая собой скрипт на Python и набор XSL-таблиц. Полученный TeX-файл, в зависимости от настроек dblatex, должен быть затем обработан LaTeX, PDFLaTeX или XeLaTeX. Я использую XeLaTeX. Он имеет следующие преимущества:

• Полная поддержка Unicode (те, кто работал с «традиционными» версиями TeX, знают, что поддержка Unicode в них реализована с помощью хитроумных хаков);
• XeLaTeX использует шрифтовую подсистему операционной системы (GDI на Windows, Freetype на Linux) вместо специфической и местами устаревшей шрифтовой подсистемы TeX. В частности, доступны все установленные в системе шрифты;
• Формат вывода по умолчанию — PDF.

Сгенерированные dblatex документы используют специальный стиль, поставляемый в комплекте dblatex. Его, конечно, можно модифицировать. XSL-таблицы из комплекта тоже можно настроить под свои задачи.

Глава 11. Вывод в CHM

Вывод в CHM поддерживается «стандартным» набором DocBook-XSL. Правда, для полноценной поддержки русского языка надо добавить следующие параметры к xsltproc:

xsltproc -stringparam chunker.output.encoding windows-1251 \
  -stringparam htmlhelp.encoding windows-1251 -stringparam chunker.output.indent yes

и в получившемся файле htmlhelp.hhp указать русский язык:

sed -i -e 's/0x0409.*/0x0419 Russian (RUSSIA)/' chm/htmlhelp.hhp

Компилятор CHM (hhc.exe) из комплекта MS HTML Help Workshop благополучно запускается под Wine, достаточно «подсунуть» ему windows-библиотеки mfc40.dll и itss.dll.

Глава 12. Поддержка составных документов

Поддержку документов, состоящих из многих файлах, в рассматриваемой схеме можно реализовать, как минимум, двумя способами. Во-первых, asciidoc сам поддерживает директиву include, работающую подобно директиве #include препроцессора C. Устанавливая значение параметра leveloffset до и после директивы include, можно «сдвинуть» все заголовки во включаемом файле (например, все заголовки первого уровня во включаемом файле будут считаться заголовками второго уровня, и т.п.). Однако для документов с большой степенью вложенности это не очень удобно, легко запутаться в значениях параметра leveloffset (осбоенно в случае, если нужно делать несколько вариантов документации в разной комплектации).

Другой вариант — использовать XInclude уже после преобразования документов в DocBook/XML. Этот вариант более гибкий и удобный. Например, можно включать не весь файл целиком, а только нужные секции. Для этого пишется ещё один XML-файл, называемый мастер-документом, в котором указана мета-информация (заголовок и т.п.), а также структура документа и набор тегов , включающих нужные разделы других документов. Но такой XML содержит мало полезной информации и много служебной разметки. Чтобы не писать мастер-файл в XML руками, я использую небольшой скрипт, делающий этот файл из YAML-файла вида

title:  Заголовок составного документа
author: Ilya V. Portnov
date:   September 2010
contents:                                 # Содержание
- programmer:                           # Здесь будут включены разделы из файла programmer.xml
- used_abbrevs                        # \
- add_docs                            #  }- Список разделов из programmer.xml
- sys_reqs                            # /
- part:                                 # Здесь будет сформирована часть документа
Концепция:                            # с заголовком part
- concept:                            # Внутрь этой части будут помещены разделы из concept.xml
- concept_goals                     # ...
- concept_components
- technologies
- concept_features
# Здесь включаются все главы, являющиеся дочерними
# по отношению к элементу 'general_descr'
- part:
Руководство программиста. общее описание:
- programmer: [ xpointer(id('general_descr')/chapter) ]
- part:
...
Руководство администратора:
- admin:
- _radixware_starter
- _radixware_server
- _radixware_manager
- user: [ _radixware_explorer ]

Таким образом получается подход, близкий к подходу DITA. Текст хранится в отдельных топиках и объединяется согласно картам документов (в формате YAML). При этом получаем даже дополнительную гибкость по сравнению с DITA, т.к. в YAML-карте документа упоминаются не только имена страниц, а и идентификаторы конкретных секций. Благодаря этому можно, например, переставить разделы в выходном документе, не меняя страниц, а меняя только карту документа.

Глава 13. Профилирование

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

DocBook предусматривает атрибуты тегов для профилирования изначально. Их поддержка в asciidoc добавляется редактированием конфигурационного файла. Например, чтобы пометить абзац как относящийся только к ОС Windows, нужно перед абзацем поместить строку [os="windows"].

Обычно для каждой задачи требуется профилирование сразу по нескольким переменным. Например, у данного заказчика OS Linux, архитектура процессора x86_64, и т.п. Чтобы не указывать каждый раз все параметры вручную, я пишу файл profiles.yaml вида

me:
os: any
audience: author
review:
os: any
audience: reviewer
some_customer:
os: linux
arch: x86_64

Здесь каждой цели профилирования сопоставлен набор пар (имя, значение), по которым должно производиться профилирование. Скрипту нужно только указать цель профилирования в качестве аргумента командной строки.

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

Глава 14. История изменений

Часто регламент требует, чтобы в начале документа присутствовала таблица, описывающая историю версий документа. Ведение такой таблицы автоматизируется благодаря тому, что для хранения документации используется git. Специальный python-скрипт анализирует вывод команды git log для каждой страницы и ищет сообщениях коммитов пометку [MAJOR] (таким образом, в сводную таблицу попадут только действительно важные изменения). Этот же скрипт пытается получить из таких сообщений версию продукта, к которой относится изменение (ищет сразу после пометки [MAJOR] строку вида PRODUCT: TXRBS-1.1.1.6). Затем другой скрипт сводит таблицы изменений для отдельных страниц в одну таблицу для всего документа и для каждого изменения указывает список изменившихся разделов.

Глава 15. Внешние ссылки

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

Эта задача у меня решается следующим образом. Во всех ссылках указываются только идентификаторы целей. При сборке xsl-стили автоматически делают внешними те ссылки, которые ссылаются на идентификаторы, определённые не в собираемом документе. В случае, когда все связанные документы описаны в одном ymap-файле, на этом этапе сборки все документы существуют в виде одного большого xml-документа (правда, он целиком никогда не формируется в виде файла, а только передаётся между скриптами через unix pipes). В такой ситуации не составляет труда с помощью xsl выяснить, какой идентификатор в каком документе определён.

В случаях же, когда некоторые из документов, на которые указывают ссылки из собираемого документа, описаны другими ymap-файлами, эти другие ymap-файлы перечисляются в собираемом ymap-файле в специальном разделе external-documents. Скрипт, преобразующий ymap в xml-документ, читает ymap-файлы, на которые ссылается данный, и в выходном xml-документе формирует тег вида

    <externs>
<document name="another_document">
 <title>Руководство администратора</title>
 <pointer target="target1"/>
 <pointer target="target2"/>
 ...
</pointer>
<document name="another_document_2">
 ...
</document>
</externs>

Таким образом, в xml-документе опять же оказывается определено, какие идентификаторы в каких документах определены, и xsl-стиль может правильно расставить внешние ссылки.

Глава 16 Полная схема сборки