Содержание


Организация совместной разработки ПО на базе SVN+DocBook+Mantis

Часть 5.2. Использование DocBook для подготовки проектной документации

Comments

Серия контента:

Этот контент является частью # из серии # статей: Организация совместной разработки ПО на базе SVN+DocBook+Mantis

Следите за выходом новых статей этой серии.

Этот контент является частью серии:Организация совместной разработки ПО на базе SVN+DocBook+Mantis

Следите за выходом новых статей этой серии.

Продолжая изучение технологии DocBook/XML, сформируем содержательную часть нашего документа в виде XML-файла, как показано в листинге 1.

Листинг 1. Пример DocBook/XML документа
<?xml version="1.0" encoding="UTF-8"?>
<article version="5.0" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Основы DocBook/XML</title>
    <author>
      <personname>
        <firstname>Алексей</firstname><surname>Баранчиков</surname>
      </personname>
      <affiliation>
        <orgname>Рязанская государственная радиотехническая академия</orgname>
      </affiliation>
    </author>
    <pubdate>17 июля 2012 года</pubdate>
  </info>
  <section>
    <title>Технология DocBook/XML</title>
    <para>DocBook — приложение SGML или XML предназначенное для разметки документов, 
    аналог HTML для разметки Web-документов.</para>
  </section>
  <section>
    <title>Сфера применения</title>
    <para>DocBook является стандартом де-факто для документации свободно
    распространяемого программного обеспечения. Его используют 
    ведущие ИТ-компании и организации: IBM, Microsoft и т.д. </para>
    <para>Использование DocBook дает наибольший эффект в следующих
    ситуациях:</para>
    <itemizedlist>
      <listitem>
        <para>когда <emphasis>объем</emphasis> документации велик</para>
      </listitem>
      <listitem>
        <para>когда в документацию постоянно приходится вносить <emphasis
        role="bold">изменения</emphasis></para>
      </listitem>
      <listitem>
        <para>когда над документацией работает коллектив</para>
      </listitem>
      <listitem>
        <para>когда документация включает в себя четко структурированные
        составляющие</para>
      </listitem>
      <listitem>
        <para>когда необходимо строго выдерживать оформление <emphasis
        role="bold">множества</emphasis> документов</para>
      </listitem>
      <listitem>
        <para>когда документацию требуется выпускать в <emphasis
        role="bold">различных форматах</emphasis></para>
      </listitem>
      <listitem>
        <para>когда требуется выпускать <emphasis>разные версии</emphasis>
        документации с отличающимся содержимым</para>
      </listitem>
    </itemizedlist>
  </section>
</article>

Очевидно, что это структурированный текстовый документ, который можно создать и отредактировать в любом текстовом редакторе. Хочу обратить внимание, что речь идет именно о текстовом редакторе, а не текстовом процессоре (OOOWrite, MS Word и т.д.). Однако вам вряд ли захочется набирать текст подобным образом. Но это и не нужно, так как существует достаточно широкий выбор специализированных XML-редакторов, которые помогут решить эту задачу. Мы не будем делать их подробный обзор (его можно найти на этой странице), а остановимся на XMLmind XML Editor.

XMLmind XML Editor

Это достаточно мощный редактор, позволяющий готовить XML-документы в нескольких форматах, в частности DITA, XHTML и, конечно, DocBook. Редактор выпускается в двух версиях: бесплатной (Personal Edition) и платной. Возможностей бесплатной версии вполне достаточно для полноценной работы с большими объемами документации. Исходный код на Java обеспечивает ему важное преимущество - многоплатформенность.

Установка XMLmind XML Editor

При установке этого редактора не должно возникнуть никаких проблем. Перейдем на Web-страницу производителя и скачаем последнюю версию продукта. В данном случае, как видно из названия дистрибутива, это версия 5.1.

Cкопируем загруженный файл в домашний каталог или любой другой:

	$cp ./Downloads/xxe-perso-5_1_1.tar.gz ~

Перейдём туда и распакуем архив:

	$cd .~
	$tar zxvf xxe-perso-5_1_1.tar.gz

Архив распаковывается в каталог ~/xxe-perso-5_1_1, в котором расположено несколько каталогов и файлов:

$ ls ./xxe-perso-5_1_1/
	addon  bin  demo  doc  legal  legal.txt

Собственно, на этом установка завершена и можно запускать редактор:

	$~/xxe-perso-5_1_1/bin/xxe

Разобраться в принципе работы редактора достаточно просто, главное — понять, что в нём игнорируется принцип WYSIWYG. Фрагмент документа, который мы рассматривали в начале статьи, будет выглядеть в редакторе следующим образом.

Рисунок 1. Пример отображения DocBook/XML-документа
Рисунок 1. Пример отображения DocBook/XML-документа
Рисунок 1. Пример отображения DocBook/XML-документа

Результат необходимо сохранить в файле docbook5_.xml.

Создание выходных документов с помощью XSL/XML

Теперь перед нами возникает следующая задача: получить полноценный выходной документ в одном из целевых форматов (форматов, предназначенных для конечного пользователя). Это преобразование может состоять из одного (целевой формат представляет структурированных текстовый файл, например, HTML) или двух (бинарный целевой файл — RTF и др.) этапов.

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

	$zypper search 'docbook*'

В полученном списке будут и нужные нам стили (docbook5-xsl-stylesheets). Далее следует установить стили указанной командой. Обратите внимание, что стили устанавливаются с правами root.

	#zypper install docbook5-xsl-stylesheets

Для просмотра краткой информации об установленном пакете используется команда

	$zypper info docbook5-xsl-stylesheets

Все стили были установлены в каталог /usr/share/xml/docbook/stylesheet/nwalsh5/1.76.1/.

Для дальнейшей работы потребуется установить библиотеку XSL-преобразований libxslt1. Эта библиотека, написанная на языке C, позволяет преобразовать XML-файлы в другие файлы, например, в HTML. Библиотека поставляется с консольной утилитой xsltproc. Теперь остается только получить файл в целевом формате (в нашем случае - это HTML):

	xsltproc --xinclude --nonet\
	/usr/share/xml/docbook/stylesheet/nwalsh5/1.76.1/html/chunk.xsl\
	docbook5_article.xml > 	index.html

Для получения файла в бинарном формате (PDF, RTF, графические форматы и т.д.) преобразование должно выполняться в два этапа. На первом этапе мы создаем промежуточный файл в формате FO (обратите внимание, что здесь мы обращаемся к другому стилю в другом каталоге).

	xsltproc --xinclude —nonet\
	 /usr/share/xml/docbook/stylesheet/nwalsh5/1.76.1/fo/docbook.xsl\ 
	docbook5_article.xml > docbook5.fo

На втором этапе воспользуемся командой fop из пакета xmlgraphics-fop и получим файл в формате RTF.

	fop docbook5.fo -rtf docbook5.rtf

Подстановкой ключей -awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at можно создать выходные файлы в соответствующих форматах. Для формата PDF присутствует определенная проблема, связанная с русской кодировкой. Она решается, но мы не будем рассматривать это решение в рамках статьи. Самый простой способ обойти эту проблему — это создать файл в формате RTF, а затем конвертировать его в PDF средствами того же OpenOffice.

Заключение

Как было продемонстрировано на практическом примере в этой и предыдущих статьях, возможностей технологии DocBook/XML вполне достаточно для поддержки и разработки документации в рамках небольшого проекта. С помощью этой технологии можно создавать различные типы документов, используя общие исходные данные, и, прибегнув к XSL-преобразованиям, получать выходные документы в различные форматах: от простых текстовых до сложных бинарных, например, PDF и RTF.


Ресурсы для скачивания


Похожие темы


Комментарии

Войдите или зарегистрируйтесь для того чтобы оставлять комментарии или подписаться на них.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Open source, Linux
ArticleID=831466
ArticleTitle=Организация совместной разработки ПО на базе SVN+DocBook+Mantis: Часть 5.2. Использование DocBook для подготовки проектной документации
publish-date=08232012