Получить стабильный поток клиентов на ваш сайт
Эффективная работа с email рассылками
Доступ к интересам вашей ЦА
Оптимизация вашего сайта для поисковых систем Яндекс и Google
Нюансы контекстной рекламы Adwords

Детали на сайте http://shareware-steps.ru

Использование 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.

4.1. Типовые конструкции Docbook

Для написания больших документов обычной практикой является создание базового индексного документа и папок с текстом и ресурсами дочерних элементов. Чаще всего разбивка дочерних документов производится на уровне глав (chapter), а разбивка на части (part) производится в основном индексном документе.

Пример 1.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 (имя файла произвольное) описываются общие атрибуты документа, история изменений и ссылки на дополнительные внешние файлы с контентом документа. Для небольших документов можно обойтись одним файлом.

Пример 1.2. Пример базового индексного документа

<?xml version="1.0" encoding="UTF-8"?>                     
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<book lang="ru">                                           
  <title>Eclipse RCP. Файловый менеджер</title>
  <bookinfo lang="ru" id="bookinfo">                       
    <author>                                               
      <firstname>Сергей</firstname>
      <surname>Бердачук</surname>
      <email>berdachuk@berdaflex.com</email>
    </author>
    <date>2006.02.28</date>

    <revhistory>                                           
      <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">                         
    <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)" />                    
     . . .
  <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>

	Заголовок документа.
	Глобальная секция book которая указывает тип документа. Для простых документов, или статей можно использовать тип документа article .
	Секция bookinfo . Содержит глобальную информацию о документе.
	Секция author . Содержит информацию об авторе.
	Секция revhistory . Содержит историю версий (ревизий) документа.
	Секция preface . Соддекжит вводную информацию по документу (введение).
	Пример включения в состав документа содержимого из внешних "дочерних" файлов.

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

Замечание

Наглядным примером сгенерированного многостраничного документа является описание процесса разработки свободного файлового менеджера "File Arranger". Данное описание доступно по адресу http://www.berdaflex.com/ru/eclipse/books/rcp_filemanager/index.html

Пример 1.3. Пример внешнего документа первой главы

<?xml version="1.0" encoding="UTF-8"?>                     
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter lang="ru">                                        
  <title>Анализ требований</title>                         
  <sect1>                                                  
    <title>Постановка задачи. Анализ</title>
    <para>Постановка ...</para>                            
    <para>Это ...</para>
    <sect2>
      <title>Предварительные требования</title>
      <para></para>
      <itemizedlist>                                       
        <listitem>
          <para>Работа с файлами (просмотр, правка, копирование, перемещение,
          добавление и удаление).</para>
        </listitem>
          . . .
        <listitem>
          <para>Возможность работы ...</para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1>
    <title>Основные задачи ...</title>
    . . .
    <figure>                                               
      <title>Диаграмма вариантов использования файлового менеджера</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/use_case_diagram1.png" />
        </imageobject>
      </mediaobject>
    </figure>
    . . .
    <orderedlist>
      <listitem>                                           
        <para>Подготовленные . . .</para>
      </listitem>
      . . .
    </orderedlist>    
  </sect1>
    . . .      
    <informaltable>                                        
      <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>                                            
        <title>Типовая структура каталогов сложного документа Docbook</title>
        . . . 
        <para><programlisting>  default.xml                
+-ch1
| |   ch1.xml
| \---images
|       adress_panel_1.png
|       . . .
+-ch2
| |   ch2.xml
| \---images
|       . . .
+-chN
| |   chN.xml
| \---images
|       . . .
+-app_a
     literature.xml
</programlisting>
      </example>  
    . . .
    <note>                                                 
      <para>Наглядным примером сгенерированного многостраничного документа
      является описание процесса разработки свободного файлового менеджера
      "File Arranger". Данное описание доступно по адресу
    <ulink                                                 
       url="http://www.berdaflex.com/ru/eclipse/books/rcp_filemanager/index.html">
       http://www.berdaflex.com/ru/eclipse/books/rcp_filemanager/index.html</ulink>
      </para>
    </note>
    . . .
    Для выделения <emphasis role="bold">жирного</emphasis> 
    текста и <emphasis>курсива</emphasis> применяются теги ...
  </sect1>
</chapter>

	Стандартный заголовок XML документа.
	Секция chapter указывает на то, что это отдельная глава документа.
	Заголовок контейнера отмечается тегом title который является обязательным для большинства контейнеров (секций).
	Секция sect1 . Секции sect1 .. sectN предназначены для структурирования документа в виде дерева подразделов. Номер указывает на уровень в дереве иерархиию
	Тег para предназначен для выделения нового параграфа и является одной из самых распространенных конструкций.
	Тег itemizedlist применяется для создания списков без нумерации. Элементы списков создаются при помощи тега listitem .
	Используя тег figure можно добавить в документ изображение (картинку). Картинка может иметь заголовок. Ссылка на внешний файл ресурса картинки задается при помощи тега imagedata который помещается в контейнер тега imageobject .
	Тег orderedlist применяется для создания списков без нумерации. Элементы списков создаются при помощи тега listitem .
	Для создания таблиц можно воспользоваться тегами informaltable , tgroup , thead , row , entry , tbody и др. Формат DocBooc позволяет создавать различное представление таблиц. В демонстрационных файлах стандартной поставки приведено большое количество примеров построения разнообразных таблиц.
	Для выделения контейнера примеров применяется тег example .
	Тег programlisting используют для выделения блоков кода, например программ.
	Для привлечения пользователя или отделения информации от основного текста применяются сноски. Тег note обычно указывает на замечание по смыслу текста; Тег important предназначен для указания читателю на важную информацию; Теги caution (предостережение) и warning (предупреждение) предназначены для предупреждения читателя о возможных проблемах. Если информацию нужно просто отделить от основного текста применяют тег sidebar .
	При помощи тега ulink можно задать гиперссылку (например на WEB ресурс).
	Для выделения жирного текста и курсива применяются тег emphasis .

Инсталляционный пакет DocBook с примерами и документацией доступны на сайте проекта по адресу http://www.docbook.org.

Пред.	Уровень выше	След.
3. Пример документа "Высокоуровневый дизайн интерфейса пользователя"	Начало	5. Как работать с документами в формате DocBook