Использование DocBook для написания документации
Уже на протяжении многих лет, XML–формат DocBook стал стандартом де–факто для разработки технической документации (в большинстве Linux–проектов применяется именно DocBook). Несмотря на наличие большого количества текстовых редакторов (Open Office Writer, Microsoft Word и т.д.), позволяющих комфортно создавать сложные текстовые документы с возможностью форматирования и интегрирования медиаресурсов, практика создания документации, написания статей и книг выявляет их главный недостаток — большие затраты времени на форматирование.
Даже использование специальных шаблонов с блокировкой ручного изменения форматов, размеров шрифтов и жесткими правилами на использование стилей не решает проблемы. Часто требуется копировать и переносить фрагменты текста между документами, что нередко сопровождается переносом элементов форматирования и смешиванием стилей между документами. Используя режим специальной вставки без форматирования в редакторе Open Office Writer или Microsoft Word эту проблему можно частично решить. Но при создании больших документов, на форматирование впустую затрачивается слишком много драгоценного времени. Некоторые издательства требуют оформления рукописей именно в формате Docbook, что упрощает и удешевляет процесс допечатной подготовки. Вторая проблема — это бинарный формат хранения файлов, который плохо подходит для совместной работы нескольких человек над документом. Если документ хранится в удаленном хранилище (например, CVS или SVN–репозитарии), то приходится заново закачивать полную копию всего документа, если он был изменен. Если документ большого размера, то это увеличивает затраты на сетевой трафик. Одновременное изменение несколькими пользователями, и слияние таких измененных документов в один весьма проблематично.
Используемый в DocBook XML–формат решает обе вышеописанные проблемы. К сожалению, заявленная поддержка данного формата в популярном редакторе Open Office Writer оставляет желать лучшего. Но на данный момент, на рынке можно найти довольно удобные альтернативные редактора, среди которых есть и бесплатные версии.
Основные преимущества формата Docbook:
Унифицированное форматирование.
Документы Docbook не содержат форматированного контента (текста, разметки страниц и т.д.). Форматирование задается при помощи унифицированного предопределенного набора тегов, на основе которых, в дальнейшем, производится трансформирование документа в произвольный формат, при помощи преобразования на основе таблиц стилей. Таблицы стилей (stylesheet) представляют собой написанные на специальных языках (XSL — Extended Specification Language или DSSSL — Document Style Semantics and Specification Language) файлы скриптов, которые описывают формат вывода различных элементов документа (используемые шрифты, форматирование, нумерацию страниц и т.д.). Использование фиксированного набора тегов гарантирует, что конечный документ будет корректно сформирован вне зависимости от количества авторов.
Работа с системами контроля версий.
Так как документы сохраняются в обычных текстовых XML–файлах, то можно легко контролировать всю историю изменения любых частей документов. Жесткая спецификация на XML–формат, упрощает процесс слияния документов при совместной работе нескольких авторов.
Модульность.
Применяемый формат позволяет легко разделить документ на независимые части для упрощения работы над большими документами. При работе удобно разбивать документ на главы, причем, широко практикуется создание документов одновременно на нескольких языках. Выбирается базовый язык (в свободных проектах обычно берут английский язык за основу), составляющие модули которого, в дальнейшем являются опорными для аналогичных модулей на других языках. При помощи исполняемых скриптов можно выбирать язык и формат генерации конечных документов.
Многовариантное представление документов.
Разделение контента и форматирования в XML–формате Docbook позволяет трансформировать один и тот же документ во множество различных форматов (например, PDF, RTF, HTML и Eclipse Help). Стандартная поставка Docbook включает примеры скриптов и таблиц стилей для трансформации в PDF, HTML и Eclipse Help.
Типовые конструкции Docbook
Для написания больших документов, обычной практикой является создание базового индексного документа и папок с текстом и ресурсами дочерних элементов. Чаще всего, разбивка дочерних документов производится на уровне глав (chapter), а разбивка на части (part) производится в основном индексном документе.
Пример 1. Типовая структура каталогов сложного документа Docbook
default.xml
+–ch1
| | ch1.xml
| \–––images
| adress_panel_1.png
| . . .
+–ch2
| | ch2.xml
| \–––images
| . . .
+–chN
| | chN.xml
| \–––images
| . . .
+–app_a
literature.xml
В базовом индексном файле default.xml (имя файла произвольное) описываются общие атрибуты документа, история изменений и ссылки на
дополнительные внешние файлы с контентом документа. Для небольших документов можно обойтись одним файлом.
Пример 2. Пример базового индексного документа
<?xml version="1.0" encoding="UTF–8"?> 1.
<!DOCTYPE book PUBLIC "–//OASIS//DTD DocBook XML V4.3//EN"
"httр://www.oasis–open.org/docbook/xml/4.3/docbookx.dtd">
<book lang="ru"> 2.
<title>Eclipse RCP. Файловый менеджер</title>
<bookinfo lang="ru" id="bookinfo"> 3.
<author> 4.
<firstname>Сергей</firstname>
<surname>Бердачук</surname>
<email>berdachuk@berdaflex.com</email>
</author>
<date>2006.02.28</date>
<revhistory> 5.
<revision>
<revnumber>0.17</revnumber>
<date>2006.05.21</date>
<revdescription>
<para>Добавлено описание создания пользовательских действий
(Actions)</para>
</revdescription>
</revision>
<revision>
. . .
</revision>
. . .
<revision>
<revnumber>0.12</revnumber>
<date>2006.02.30</date>
</revision>
</revhistory>
</bookinfo>
<preface lang="ru" id="preface"> 6.
<title>Введение</title>
<epigraph>
<para>
<emphasis>Теория без практики ...</emphasis>
</para>
</epigraph>
<para>Данный материал ...</para>
<para>По ходу ...</para>
. . .
</preface>
<xi:include href="ch1/ch1.xml" xmlns:xi=" http://www.w3.org/2001/XInclude"
xpointer="element(/1)" /> 7.
. . .
<xi:include href="ch4/ch4.xml" xmlns:xi=" http://www.w3.org/2001/XInclude"
xpointer="element(/1)" />
<xi:include href="app_a/literature.xml"
xmlns:xi=" http://www.w3.org/2001/XInclude"
xpointer="element(/1)" />
</book>
1. Заголовок документа.
2. Глобальная секция book, которая указывает тип документа. Для простых документов или статей можно использовать тип документа article.
3. Секция bookinfo содержит глобальную информацию о документе.
4. Секция author содержит информацию об авторе.
5. Секция revhistory содержит историю версий (ревизий) документа.
6. Секция preface содержит вводную информацию по документу (введение).
7. Пример включения в состав документа содержимого из внешних файлов.
Формат DocBook содержит большое количество тегов, которые позволяют создавать документы сложной структуры. Но практика показывает, что вполне можно обойтись знанием одного или двух десятков тегов. При необходимости создания незнакомых конструкций, можно посмотреть, как это сделано в примерах, которые входят в поставку стандартного инсталляционного пакета.
Замечание
Наглядным примером сгенерированного многостраничного документа является описание процесса разработки свободного файлового менеджера "File Arranger". Оно доступно по адресу сайт
Пример 3. Пример внешнего документа первой главы
<?xml version="1.0" encoding="UTF–8"?> 1.
<chapter lang="ru"> 2.
<title>Анализ требований</title> 3.
<sect1> 4.
<title>Постановка задачи. Анализ</title>
<para>Постановка ...</para> 5.
<para>Это ...</para>
<sect2>
<title>Предварительные требования</title>
<para></para>
<itemizedlist> 6.
<listitem>
<para>Работа с файлами (просмотр, правка, копирование, перемещение, добавление и удаление).</para>
</listitem>
. . .
<listitem>
<para>Возможность работы ...</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1>
<title>Основные задачи ...</title>
. . .
<figure> 7.
<title>Диаграмма вариантов использования файлового менеджера</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/use_case_diagram1.png" />
</imageobject>
</mediaobject>
</figure>
. . .
<orderedlist>
<listitem> 8.
<para>Подготовленные . . .</para>
</listitem>
. . .
</orderedlist>
</sect1>
. . .
<informaltable> 9.
<tgroup cols="2">
<thead>
<row>
<entry align="center">Значок</entry>
<entry align="center">Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry><inlinemediaobject>
<imageobject>
<imagedata fileref="images/btn_show_panel.png" />
</imageobject>
</inlinemediaobject></entry>
<entry>Показать навигационную панель</entry>
</row>
. . .
<row>
. . .
</row>
</tbody>
</tgroup>
</informaltable>
. . .
<sect1>
<title>Использование DocBook для написания документации</title>
. . .
<para>Основные преимущества формата Docbook:</para>
<example> 10.
<title>Типовая структура каталогов сложного документа Docbook</title>
. . .
<para><programlisting> default.xml 11.
+–ch1
| | ch1.xml
| \–––images
| adress_panel_1.png
| . . .
+–ch2
| | ch2.xml
| \–––images
| . . .
+–chN
| | chN.xml
| \–––images
| . . .
+–app_a
literature.xml
</programlisting>
</example>
. . .
<note> 12.
<para>Наглядным примером сгенерированного многостраничного документа
является описание процесса разработки свободного файлового менеджера
"File Arranger". Данное описание доступно по адресу
<ulink 13.
url="httр://www.berdaflex.com/ru/eclipse/books/rcp_filemanager/index.html">
httр://www.berdaflex.com/ru/eclipse/books/rcp_filemanager/index.html.</ulink>
</para>
</note>
. . .
Для выделения <emphasis role="bold">жирного</emphasis> 14.
текста и <emphasis>курсива</emphasis> применяются теги ...
</sect1>
</chapter>
1. Стандартный заголовок XML–документа.
2. Секция chapter указывает на то, что это отдельная глава документа.
3. Заголовок контейнера отмечается тегом title, который является обязательным для большинства контейнеров (секций).
4. Секция sect1. Секции sect1 ... sectN предназначены для структурирования документа в виде дерева подразделов. Номер указывает на уровень в дереве
5 .Тег para предназначен для выделения нового параграфа и является одной из самых распространенных конструкций.
6. Тег itemizedlist применяется для создания списков без нумерации. Элементы списков создаются при помощи тега listitem.
7. Используя тег figure, можно добавить в документ изображение (картинку). Картинка может иметь заголовок. Ссылка на внешний файл ресурса картинки задается при помощи тега imagedata, который помещается в контейнер тега imageobject.
8. Тег orderedlist применяется для создания списков без нумерации. Элементы списков создаются при помощи тега listitem.
9. Для создания таблиц можно воспользоваться тегами informaltable, tgroup, thead, row, entry, tbody и др. Формат DocBook позволяет создавать различное представление таблиц. В демонстрационных файлах стандартной поставки приведено большое количество примеров построения разнообразных таблиц.
10. Для выделения контейнера примеров применяется тег example.
11. Тег programlisting используют для выделения блоков кода, например, программ.
12. Для привлечения пользователя или отделения информации от основного текста применяются сноски:
— тег note обычно указывает на замечание по смыслу текста;
— тег important предназначен для указания на важную информацию;
— теги caution (предостережение) и warning (предупреждение) предназначены для предупреждения о возможных проблемах;
— если информацию нужно просто отделить от основного текста, применяют тег sidebar.
13. При помощи тега ulink можно задать гиперссылку (например, на web–ресурс).
14. Для выделения жирного текста и курсива применяются тег emphasis.
Инсталляционный пакет DocBook с примерами и документацией доступны на сайте проекта по адресу сайт
Сергей Бердачук http://www.berdaflex.com
Даже использование специальных шаблонов с блокировкой ручного изменения форматов, размеров шрифтов и жесткими правилами на использование стилей не решает проблемы. Часто требуется копировать и переносить фрагменты текста между документами, что нередко сопровождается переносом элементов форматирования и смешиванием стилей между документами. Используя режим специальной вставки без форматирования в редакторе Open Office Writer или Microsoft Word эту проблему можно частично решить. Но при создании больших документов, на форматирование впустую затрачивается слишком много драгоценного времени. Некоторые издательства требуют оформления рукописей именно в формате Docbook, что упрощает и удешевляет процесс допечатной подготовки. Вторая проблема — это бинарный формат хранения файлов, который плохо подходит для совместной работы нескольких человек над документом. Если документ хранится в удаленном хранилище (например, CVS или SVN–репозитарии), то приходится заново закачивать полную копию всего документа, если он был изменен. Если документ большого размера, то это увеличивает затраты на сетевой трафик. Одновременное изменение несколькими пользователями, и слияние таких измененных документов в один весьма проблематично.
Используемый в DocBook XML–формат решает обе вышеописанные проблемы. К сожалению, заявленная поддержка данного формата в популярном редакторе Open Office Writer оставляет желать лучшего. Но на данный момент, на рынке можно найти довольно удобные альтернативные редактора, среди которых есть и бесплатные версии.
Основные преимущества формата Docbook:
Унифицированное форматирование.
Документы Docbook не содержат форматированного контента (текста, разметки страниц и т.д.). Форматирование задается при помощи унифицированного предопределенного набора тегов, на основе которых, в дальнейшем, производится трансформирование документа в произвольный формат, при помощи преобразования на основе таблиц стилей. Таблицы стилей (stylesheet) представляют собой написанные на специальных языках (XSL — Extended Specification Language или DSSSL — Document Style Semantics and Specification Language) файлы скриптов, которые описывают формат вывода различных элементов документа (используемые шрифты, форматирование, нумерацию страниц и т.д.). Использование фиксированного набора тегов гарантирует, что конечный документ будет корректно сформирован вне зависимости от количества авторов.
Работа с системами контроля версий.
Так как документы сохраняются в обычных текстовых XML–файлах, то можно легко контролировать всю историю изменения любых частей документов. Жесткая спецификация на XML–формат, упрощает процесс слияния документов при совместной работе нескольких авторов.
Модульность.
Применяемый формат позволяет легко разделить документ на независимые части для упрощения работы над большими документами. При работе удобно разбивать документ на главы, причем, широко практикуется создание документов одновременно на нескольких языках. Выбирается базовый язык (в свободных проектах обычно берут английский язык за основу), составляющие модули которого, в дальнейшем являются опорными для аналогичных модулей на других языках. При помощи исполняемых скриптов можно выбирать язык и формат генерации конечных документов.
Многовариантное представление документов.
Разделение контента и форматирования в XML–формате Docbook позволяет трансформировать один и тот же документ во множество различных форматов (например, PDF, RTF, HTML и Eclipse Help). Стандартная поставка Docbook включает примеры скриптов и таблиц стилей для трансформации в PDF, HTML и Eclipse Help.
Типовые конструкции Docbook
Для написания больших документов, обычной практикой является создание базового индексного документа и папок с текстом и ресурсами дочерних элементов. Чаще всего, разбивка дочерних документов производится на уровне глав (chapter), а разбивка на части (part) производится в основном индексном документе.
Пример 1. Типовая структура каталогов сложного документа Docbook
default.xml
+–ch1
| | ch1.xml
| \–––images
| adress_panel_1.png
| . . .
+–ch2
| | ch2.xml
| \–––images
| . . .
+–chN
| | chN.xml
| \–––images
| . . .
+–app_a
literature.xml
В базовом индексном файле default.xml (имя файла произвольное) описываются общие атрибуты документа, история изменений и ссылки на
дополнительные внешние файлы с контентом документа. Для небольших документов можно обойтись одним файлом.
Пример 2. Пример базового индексного документа
<?xml version="1.0" encoding="UTF–8"?> 1.
<!DOCTYPE book PUBLIC "–//OASIS//DTD DocBook XML V4.3//EN"
"httр://www.oasis–open.org/docbook/xml/4.3/docbookx.dtd">
<book lang="ru"> 2.
<title>Eclipse RCP. Файловый менеджер</title>
<bookinfo lang="ru" id="bookinfo"> 3.
<author> 4.
<firstname>Сергей</firstname>
<surname>Бердачук</surname>
<email>berdachuk@berdaflex.com</email>
</author>
<date>2006.02.28</date>
<revhistory> 5.
<revision>
<revnumber>0.17</revnumber>
<date>2006.05.21</date>
<revdescription>
<para>Добавлено описание создания пользовательских действий
(Actions)</para>
</revdescription>
</revision>
<revision>
. . .
</revision>
. . .
<revision>
<revnumber>0.12</revnumber>
<date>2006.02.30</date>
</revision>
</revhistory>
</bookinfo>
<preface lang="ru" id="preface"> 6.
<title>Введение</title>
<epigraph>
<para>
<emphasis>Теория без практики ...</emphasis>
</para>
</epigraph>
<para>Данный материал ...</para>
<para>По ходу ...</para>
. . .
</preface>
<xi:include href="ch1/ch1.xml" xmlns:xi=" http://www.w3.org/2001/XInclude"
xpointer="element(/1)" /> 7.
. . .
<xi:include href="ch4/ch4.xml" xmlns:xi=" http://www.w3.org/2001/XInclude"
xpointer="element(/1)" />
<xi:include href="app_a/literature.xml"
xmlns:xi=" http://www.w3.org/2001/XInclude"
xpointer="element(/1)" />
</book>
1. Заголовок документа.
2. Глобальная секция book, которая указывает тип документа. Для простых документов или статей можно использовать тип документа article.
3. Секция bookinfo содержит глобальную информацию о документе.
4. Секция author содержит информацию об авторе.
5. Секция revhistory содержит историю версий (ревизий) документа.
6. Секция preface содержит вводную информацию по документу (введение).
7. Пример включения в состав документа содержимого из внешних файлов.
Формат DocBook содержит большое количество тегов, которые позволяют создавать документы сложной структуры. Но практика показывает, что вполне можно обойтись знанием одного или двух десятков тегов. При необходимости создания незнакомых конструкций, можно посмотреть, как это сделано в примерах, которые входят в поставку стандартного инсталляционного пакета.
Замечание
Наглядным примером сгенерированного многостраничного документа является описание процесса разработки свободного файлового менеджера "File Arranger". Оно доступно по адресу сайт
Пример 3. Пример внешнего документа первой главы
<?xml version="1.0" encoding="UTF–8"?> 1.
<chapter lang="ru"> 2.
<title>Анализ требований</title> 3.
<sect1> 4.
<title>Постановка задачи. Анализ</title>
<para>Постановка ...</para> 5.
<para>Это ...</para>
<sect2>
<title>Предварительные требования</title>
<para></para>
<itemizedlist> 6.
<listitem>
<para>Работа с файлами (просмотр, правка, копирование, перемещение, добавление и удаление).</para>
</listitem>
. . .
<listitem>
<para>Возможность работы ...</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1>
<title>Основные задачи ...</title>
. . .
<figure> 7.
<title>Диаграмма вариантов использования файлового менеджера</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/use_case_diagram1.png" />
</imageobject>
</mediaobject>
</figure>
. . .
<orderedlist>
<listitem> 8.
<para>Подготовленные . . .</para>
</listitem>
. . .
</orderedlist>
</sect1>
. . .
<informaltable> 9.
<tgroup cols="2">
<thead>
<row>
<entry align="center">Значок</entry>
<entry align="center">Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry><inlinemediaobject>
<imageobject>
<imagedata fileref="images/btn_show_panel.png" />
</imageobject>
</inlinemediaobject></entry>
<entry>Показать навигационную панель</entry>
</row>
. . .
<row>
. . .
</row>
</tbody>
</tgroup>
</informaltable>
. . .
<sect1>
<title>Использование DocBook для написания документации</title>
. . .
<para>Основные преимущества формата Docbook:</para>
<example> 10.
<title>Типовая структура каталогов сложного документа Docbook</title>
. . .
<para><programlisting> default.xml 11.
+–ch1
| | ch1.xml
| \–––images
| adress_panel_1.png
| . . .
+–ch2
| | ch2.xml
| \–––images
| . . .
+–chN
| | chN.xml
| \–––images
| . . .
+–app_a
literature.xml
</programlisting>
</example>
. . .
<note> 12.
<para>Наглядным примером сгенерированного многостраничного документа
является описание процесса разработки свободного файлового менеджера
"File Arranger". Данное описание доступно по адресу
<ulink 13.
url="httр://www.berdaflex.com/ru/eclipse/books/rcp_filemanager/index.html">
httр://www.berdaflex.com/ru/eclipse/books/rcp_filemanager/index.html.</ulink>
</para>
</note>
. . .
Для выделения <emphasis role="bold">жирного</emphasis> 14.
текста и <emphasis>курсива</emphasis> применяются теги ...
</sect1>
</chapter>
1. Стандартный заголовок XML–документа.
2. Секция chapter указывает на то, что это отдельная глава документа.
3. Заголовок контейнера отмечается тегом title, который является обязательным для большинства контейнеров (секций).
4. Секция sect1. Секции sect1 ... sectN предназначены для структурирования документа в виде дерева подразделов. Номер указывает на уровень в дереве
5 .Тег para предназначен для выделения нового параграфа и является одной из самых распространенных конструкций.
6. Тег itemizedlist применяется для создания списков без нумерации. Элементы списков создаются при помощи тега listitem.
7. Используя тег figure, можно добавить в документ изображение (картинку). Картинка может иметь заголовок. Ссылка на внешний файл ресурса картинки задается при помощи тега imagedata, который помещается в контейнер тега imageobject.
8. Тег orderedlist применяется для создания списков без нумерации. Элементы списков создаются при помощи тега listitem.
9. Для создания таблиц можно воспользоваться тегами informaltable, tgroup, thead, row, entry, tbody и др. Формат DocBook позволяет создавать различное представление таблиц. В демонстрационных файлах стандартной поставки приведено большое количество примеров построения разнообразных таблиц.
10. Для выделения контейнера примеров применяется тег example.
11. Тег programlisting используют для выделения блоков кода, например, программ.
12. Для привлечения пользователя или отделения информации от основного текста применяются сноски:
— тег note обычно указывает на замечание по смыслу текста;
— тег important предназначен для указания на важную информацию;
— теги caution (предостережение) и warning (предупреждение) предназначены для предупреждения о возможных проблемах;
— если информацию нужно просто отделить от основного текста, применяют тег sidebar.
13. При помощи тега ulink можно задать гиперссылку (например, на web–ресурс).
14. Для выделения жирного текста и курсива применяются тег emphasis.
Инсталляционный пакет DocBook с примерами и документацией доступны на сайте проекта по адресу сайт
Сергей Бердачук http://www.berdaflex.com
Компьютерная газета. Статья была опубликована в номере 26 за 2006 год в рубрике программирование
