DocBook

DocBook — это семейство схем для разметки технической документации, основанное на языке XML (ранее — SGML). DocBook предоставляет набор семантических элементов (тегов) для описания структуры книг, статей, руководств, справочников и другой документации, позволяя отделить содержание от визуального представления. Файлы DocBook обрабатываются инструментарием (например, XSLT-преобразованиями) для генерации конечных форматов: HTML, PDF, EPUB, CHM, PostScript и других.

История

Изначально DocBook был разработан в 1991 году компанией HaL Computer Systems совместно с O’Reilly & Associates для публикации технической документации по программному обеспечению. Первая версия DTD (Document Type Definition) была создана на языке SGML. В 1994 году проект перешёл под управление некоммерческой организации Davenport Group, а затем — в 1998 году — в ведение OASIS (Organization for the Advancement of Structured Information Standards).

В 1999 году вышла версия 3.1, последняя на SGML. В 2000 году была выпущена версия 4.0, переведённая на XML, что упростило интеграцию с современными инструментами обработки. В 2005 году, после версии 4.4, OASIS прекратила активное развитие DTD-варианта и сосредоточилась на разработке релаксированной схемы (RELAX NG) и схемы W3C XML Schema.

В 2006 году появился DocBook V5.0, ставший основным релизом на RELAX NG. Эта версия внесла значительные изменения: удалены устаревшие элементы, введены пространства имён, добавлена поддержка модульных расширений. Текущая стабильная версия — DocBook V5.1 (выпущена в 2016 году). Разработку курирует DocBook Technical Committee при OASIS.

Структура и элементы

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

• Корневые элементы: book (книга), article (статья), set (набор книг), part (часть), appendix (приложение). Они задают верхний уровень структуры.
• Метаданные: <info> (сведения о документе: автор, дата, версия, лицензия), <title> (заголовок), <copyright> (копирайт), <revhistory> (история изменений).
• Блочные элементы: <para> (абзац), <section> (раздел), <simplesect> (простой раздел без подзаголовков), <orderedlist> (нумерованный список), <itemizedlist> (маркированный список), <table> (таблица), <figure> (рисунок), <example> (пример), <programlisting> (листинг кода).
• Инлайновые элементы: <emphasis> (акцент), <literal> (буквальный текст), <code> (код), <filename> (имя файла), <option> (ключ команды), <parameter> (параметр), <glossterm> (термин), <link> (ссылка), <xref> (перекрёстная ссылка).
• Специализированные: <procedure> (последовательность шагов), <step> (шаг процедуры), <warning> (предупреждение), <note> (примечание), <tip> (совет), <caution> (осторожно), <danger> (опасность).
• Индексирование: <index> (указатель), <glossary> (глоссарий).

Пример фрагмента XML-документа DocBook:

``xml <book xmlns="http://docbook.org/ns/docbook"; version="5.0"> <info> <title>Руководство пользователя Системы</title> <author> <personname>Иван Иванов</personname> </author> <pubdate>2023</pubdate> </info> <chapter> <title>Установка</title> <para>Для установки выполните команду:</para> <programlisting>sudo apt install package</programlisting> </chapter> </book> ``

Обработка и инструментарий

Основной метод обработки DocBook — преобразование с помощью XSLT (Extensible Stylesheet Language Transformations). Стандартные стили (DocBook XSL Stylesheets) предоставляются проектом DocBook и позволяют генерировать:

• HTML (одна страница или набор страниц)
• PDF (через XSL-FO или LaTeX)
• EPUB
• CHM (справочные файлы Windows)
• Простой текст (plain text)
• RTF (через FO-processor)

Для сборки часто используются инструменты:

• xsltproc (из состава libxslt) — утилита командной строки для XSLT-преобразований.
• Apache FOP — форматтер XSL-FO для генерации PDF.
• Dblatex — утилита для преобразования DocBook в PDF через LaTeX.
• Pandoc — конвертер документов, поддерживающий чтение DocBook.

Современные рабочие процессы могут использовать системы автоматизации сборки (Make, Maven, SCons) или интегрированные среды (XMLmind XML Editor, oXygen XML Editor).

Применение

DocBook получил широкое распространение в open-source сообществе и в индустрии, особенно для проектов, требующих единого формата документации из одного исходника. Наиболее известные проекты, использующие DocBook:

• Ядро Linux — документация по ядру (Documentation/*.xml) исторически частично использовала DocBook, хотя сейчас переходит на другие форматы (ReStructuredText).
• GNOME — документация по среде рабочего стола и приложениям (Yelp Help System использует DocBook).
• KDE — документация KDE Applications.
• FreeBSD — документация по операционной системе (Handbook на DocBook).
• Mozilla (Firefox, Thunderbird) — в прошлом активно использовали DocBook для справочной системы.
• Apache Software Foundation — ряд проектов (например, Apache Tomcat) используют DocBook для своих мануалов.
• O‘Reilly Media — издательство технической литературы, где DocBook использовалось для создания ряда книг.

Преимущества

• Семантическая разметка: позволяет авторам описывать тип содержания (шаг, параграф, листинг), а не формат (жирный, отступ). Это упрощает автоматический вывод разных выходных форматов.
• Единый источник (Single Sourcing): из одного XML-файла можно получить PDF, HTML, EPUB и другие форматы без ручного переформатирования.
• Гибкость повторного использования: элементы можно включать из других документов с помощью xi:include, что удобно для многостраничной документации.
• Расширяемость: схему можно дополнять собственными элементами с помощью кастомизаций (customization layer).
• Стандартизация: DocBook является открытым стандартом OASIS, что обеспечивает переносимость между инструментами.

Недостатки и критика

• Сложность: полная схема DocBook содержит несколько сотен элементов, что требует значительного времени на изучение.
• Избыточность: для простых документов (несколько страниц) DocBook может быть излишне громоздким. Существуют более лёгкие альтернативы, такие как AsciiDoc или Markdown.
• Зависимость от инструментов: для обработки необходимо устанавливать и настраивать XSLT-стили и рендереры, что может быть неудобно для небольших проектов.
• Устаревший синтаксис: некоторые решения (например, использование imagedata для вставки изображений) выглядят архаично на фоне современных форматов.
• Конкуренция: DocBook теряет популярность в пользу более простых языков разметки (Markdown, reStructuredText, AsciiDoc), которые требуют меньше усилий для написания и обработки, особенно для онлайн-документации.

Альтернативы

• AsciiDoc — более простой формат со встроенной системой преобразования, активно используется для проектов на GitHub и в документации ПО.
• reStructuredText (reST) — язык разметки на Python, используемый в Sphinx для создания документации.
• Markdown — минималистичный язык с широкой поддержкой в вебе, часто дополняется расширениями (например, Pandoc Markdown).
• LaTeX — система вёрстки, ориентированная на научные и технические публикации, обладает лучшим качеством вывода PDF, но сложнее в настройке.

Источники

• Руководство DocBook Technical Committee (OASIS)
• Документация проекта DocBook (docbook.org)
• Статья «DocBook» в «WikiBooks» (рус.)
• База знаний «XML.com»
• «DocBook: The Definitive Guide» by Norman Walsh and Leonard Muellner (O’Reilly Media)