Подготовка документации и повторное использование информации в XML: Часть 1. Публикация документов с использованием XML

Создание, форматирование и публикация документов с использованием стандартов XML и инструментальных программ с открытым исходным кодом

Технология XML, предоставляющая способ идентификации элементов данных и дочерних компонентов в рамках любого набора структурированных данных, прочно обосновалась в разработке и изготовлении документации. Развитые открытые стандарты для разметки XML-документов и богатый набор бесплатных программ для синтаксического анализа XML-документов и преобразования форматов позволяют легко создать и настроить законченную среду подготовки и форматирования документации на любой UNIX®- или Linux®-системе.

Уильям фон Хаген, системный администратор, писатель, WordSmiths

Уильям фон Хаген (William von Hagen) уже более 20 лет занимается написанием статей и книг и администрированием UNIX-систем, а с 1993 года – пропагандой Linux. Он автор и соавтор книг о Ubuntu Linux, Xen Virtualization, GNU Compiler Collection (GCC), SUSE Linux, Mac OS X, файловых системах Linux и SGML. Он также написал множество статей по Linux и Mac OS X для печатных изданий и для Web-сайтов.



21.12.2009

XML, разметка и документация

Технология XML разрабатывалась как механизм идентификации структурированного содержимого внутри набора данных путем инкапсуляции различных иерархических фрагментов этих данных в текстовые теги, идентифицирующие роль текста, которую они очерчивают в рамках этой иерархии. Эти текстовые теги, называемые разметкой (markup), тегами (tags) или, более корректно, элементами (elements), подчиняются предопределенной структуре. Эта структура является специфичной для данных различного типа и называется схемой (schema) или, в прошлом, DTD. Схемы записываются на языке XML, тогда как DTD имеют свой собственный синтаксис.

Часто используемые сокращения

  • DTD: Document Type Definition (определение типа документа)
  • HTML: Hypertext Markup Language (язык разметки гипертекста)
  • XHTML: Extensible Hypertext Markup Language (расширяемый язык разметки гипертекста)
  • XML: Extensible Markup Language (расширяемый язык разметки)
  • XSL: Extensible Stylesheet Language (расширяемый язык таблицы стилей)

Идея языков разметки, и XML в том числе, берет начало с систем подготовки документации, в которых текстовые файлы содержали команды обработки или структурные идентификаторы для различных фрагментов документа. Эти текстовые файлы могли затем обрабатываться программным обеспечением, умеющим интерпретировать эти команды и формирующим выходные данные, отформатированные для определенного устройства вывода. Эволюция языков разметки для документации привела к повышению уровня абстракции использования разметки.

Первые языки разметки использовали команды форматирования, которые указывали такие низкоуровневые характеристики, как изменения шрифта и его размера. Они быстро развились в более обобщенные языки разметки, идентифицировавшие логические и структурные компоненты, такие как выделенные термины, параграфы, списки, заголовки и т.д.

Более современные языки разметки, такие как SGML (Standard Generalized Markup Language) и XML, популяризовали более абстрактную структурную разметку, например, на книги, главы, разделы и т.д. В SGML также было введена концепция DTD, которая позволила SGML-средствам контролировать соответствие документа заданному набору элементов разметки и контексту, в котором эти элементы могут появляться внутри структуры документа определенного типа.

Технология XML вывела языки разметки из царства документации, расширив его использование на любые типы структурированных данных и добавив требование правильно сформированного (well-formed) содержимого, когда для каждого элемента обязательно должны присутствовать как открывающий, так и закрывающий теги. Хотя первые версии спецификации XML унаследовали DTD из SGML, в более поздних версиях спецификации было введено использование схем для определения структуры XML-данных. Схемы являются эквивалентом DTD, но они сами также записываются на XML и реализуют более гибкую модель для определения корректных элементов, их типов данных и контекста, в котором они могут появляться в XML-документе.

Идея отделения содержимого документа (фактических слов или данных, которые он содержит) от его представления (способа его отображения в определенном выходном формате или на определенном устройстве вывода) является ключевым принципом, лежащим в основе современных языков разметки и, в частности, SGML и XML.

Хотя XML облегчает разработку DTD и схем для конкретных приложений и отраслей, одним из больших его преимуществ в области документирования является существование нескольких стандартных DTD и схем для разметки документации. Наиболее известными из них являются DocBook, Text Encoding Initiative (TEI), XHTML, а также схемы и DTD, применяемые в архитектуре DITA (Darwin Information Typing Architecture). В данной статье основное внимание уделяется DocBook, которая является самой известной и широко используемой схемой для разметки документации.

Обзор процесса публикации для XML-документов

Из-за своей направленности на отделение содержимого от представления XML является механизмом типа "написать один раз, читать много раз", облегчающим повторное использование информации в разных документах и настройку информации для конкретного выходного формата или аудитории. Более подробно данная тема будет освещена в других статьях данной серии.

В контексте данной статьи понятие публикации обозначает преобразование документа из текстового файла, содержащего разметку DocBook, в один или несколько выходных файлов в конкретных форматах представления, например HTML, Adobe®'s Portable Document Format (PDF), PostScript, Microsoft®'s Rich Text Format (RTF) и т.д. Генерирование HTML-данных из XML-документов представляет собой одношаговый процесс, который использует одно приложение для генерирования HTML. Процесс подготовки PDF, PostScript или RTF-данных требует единственного дополнительного действия:

  1. Разрешите все включаемые файлы и внешние ссылки в DocBook-документе и с помощью таблицы стилей (stylesheet) XSL сгенерируйте версию этого документа в формате Formatting Object (FO).
  2. Для PDF, PostScript или RTF-данных преобразуйте версию FO DocBook-документа в выходной файл в указанном формате.

Для выполнения этих преобразований существует множество инструментальных программ с открытым исходным кодом, но в данной статье внимание концентрируется на трех программах, которые, по моему мнению, предоставляют наиболее удобные и гибкие решения. Эти программы перечислены в таблице 1.

Таблица 1. Программы преобразования с открытым исходным кодом, рассматриваемые в данной статье
ПрограммаОписание
fopJava™-приложение, преобразующее входные XML-данные в выходные форматы PDF, PostScript, RTF и т.д. Для выполнения приложения необходимо установить Java Virtual Machine (JVM).
xmltoПростой сценарий командной оболочки Bourne-Again и набор таблиц стилей, формирующих HTML из XML-данных. Для работы этому сценарию нужны некоторые другие вспомогательные программы с открытым исходным кодом, например, GNU find и mktemp.
xsltprocКомпилированное приложение, использующее таблицы стилей XSL для преобразования входных XML-данных в другой XML-формат. Для выполнения такого преобразования необходимо установить таблицы стилей XSL DocBook. Хотя fop может принимать входные XML-данные DocBook при наличии соответствующей таблицы стилей, использование такого автономного преобразователя XML в FO, как xsltproc упрощает отладку, если во входных DocBook-файлах имеются какие-либо проблемы.

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

Получение и установка необходимого программного обеспечения

Информация о том, где получить пакеты, содержащие рассматриваемое в предыдущем разделе программное обеспечение и таблицы стилей, приведена в разделе "Ресурсы".

Примечание. Если вы используете систему Linux, есть большая вероятность, что программы xmlto и xsltproc уже установлены или по крайней мере имеются в репозиториях или на установочных дисках вашего дистрибутива. Необходимо установить также реальную JVM для запуска fop - компилятор GNU для Java не предоставляет всех функциональных возможностей, необходимых для работы fop.

Многие из этих пакетов устанавливают программное обеспечение в определенное место, поэтому системные программы управления пакетами могут следить за этими программами и обновлять их по мере необходимости. Это не относится к таблицам стилей XSL DocBook и Apache Formatting Objects Processor (FOP), которые загружаются как архивные файлы, содержащие один каталог высшего уровня и различные подкаталоги.

Для унификации синтаксического анализа документации и среды форматирования рекомендуется установить все пакеты, не имеющие жестко определенных путей к каталогам, в один новый каталог, например /home/doc. При этом создается единое место, где вы можете искать нужные файлы, обновлять при необходимости программное обеспечение и собирать дополнительные программы и таблицы стилей, которые вы, возможно, разработаете или найдете.

Чтобы рассмотренные выше пакеты работали с универсальным сценарием, описанным в следующем разделе, выполните команды, приведенные в листинге 1, под пользователем root на вашей системе UNIX или Linux.

Листинг 1. Команды, которые нужно выполнить, чтобы fop, xmlto и xsltproc работали с универсальным сценарием
      mkdir /home/doc
      mkdir /home/doc/bin
      mkdir /home/doc/external
      mkdir /home/doc/external/SAVE
      mkdir /home/doc/XSL

После загрузки архивированных (.zip) файлов для FOP и таблиц стилей XSL DocBook поместите их в каталог /home/doc/external, перейдите в этот каталог и извлеките их содержимое, используя команды, приведенные в листинге 2.

Листинг 2. Команды для извлечения FOP и таблиц стилей XSL DocBook
      cd /home/doc/external
      unzip fop-0.95-bin.zip
      unzip docbook-xsl-1.74.3.zip
      chmod 755 fop-0.95/fop

Для проверки наличия всех необходимых пакетов в системе выполните команды, приведенные в листинге 3.

Листинг 3. Команды для проверки наличия всех необходимых пакетов
      xmlto --version
      xsltproc --version
      java --version

Если приложения xmlto и xsltproc и JVM установлены корректно и имеются в пути исполнения (execution path), каждая из этих команд возвратит информацию о версии данного приложения.

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

Теперь, после установки всего необходимого для публикации DocBook программного обеспечения, осталось только запомнить необходимые параметры и выполнять действия в правильном порядке. Можно также написать универсальный сценарий, объединяющий все действия в нужной последовательности и предоставляющий определенные возможности для управления процессом публикации. Пример такого сценария приведен в листингах 4, 5 и 6.

Этот сценарий генерирует выходные данные в форматах HTML, PDF или RTF в зависимости от переданных ему аргументов. При генерировании PDF или RTF он использует двухшаговый процесс, сначала с помощью xsltproc, генерируя FO-файл из входных DocBook-данных с использованием таблицы стилей XSL, указанной в переменной driverfile, которая определяет правила преобразования. Затем универсальный сценарий с помощью приложения fop генерирует указанный выходной формат из этого файла. На каждом из этих шагов в файлы xsltproc.out и fop.out собираются сообщения из использующихся приложений (xsltproc и fop). Сценарий использует эти промежуточные файлы для мониторинга процесса преобразования и сбора потенциальной отладочной информации, полезной при возникновении каких-либо проблем.

В листинге 4 показано начало примера универсального сценария, в котором определяется сообщение usage, отображающееся при выполнении сценария без аргументов или с неверным числом аргументов. В нем также устанавливаются некоторые значения по умолчанию и анализируются аргументы командной строки при помощи стандартной функции оболочки Bash - getoptлистинге 7 показана выходная информация этого сообщения usage).

Листинг 4. Раздел инициализации простого универсального сценария
#! /bin/bash 
#
# Простой сценарий для генерирования выходных HTML-данных из DocBook-файла 
# при помощи xmlto или для генерирования выходных PDF/RTF-данных путем 
# генерирования fo-файла и последующего использования Apache FOP для его 
# форматирования.
#
# wvh@vonhagen.org
#

function usage {
        echo "Usage: $0 [OPTIONS] document-name"
        echo "  -D : produce draft mode document" 
        echo "  -d : use specified xsl driver (requires name of XSL file) "
        echo "  -h : generate HTML output (requires output directory name)"
        echo "  -k : attempt PDF generation even if xsltproc errors were encountered"
        echo "  -n : suppress TOC" 
        echo "  -r : produce RTF output rather than PDF" 
        exit 1
}

dir=`dirname $0`

XSLTPROC="xsltproc"
PATH=$dir/../external/fop-0.95:${PATH}

if [ $# == 0 ] ; then
        usage
        exit 
fi

driverfile="$dir/../external/docbook-xsl-1.74.3/fo/docbook.xsl"
# driverfile="$dir/../XSL/generic-print-driver.xsl"
draft="no"
keepgoing="no"
RTFoutput="no"
HTMLoutput="no"

while getopts ":d:h:Dknr" opt
do
  case $opt in
      d  ) 
           driverfile=$OPTARG
           echo "Using driver file: $driverfile"
           if [ ! -f $driverfile ] ; then
               echo "  Driver file not found"
               exit 1
           fi
           ;;
      D  )
           draft="yes"
           echo "Producing Draft Mode Document"
           ;;
      h  )
           HTMLdir=$OPTARG
           HTMLoutput="yes"
           echo "Producing HTML output to $HTMLdir instead of PDF"
           if [ -d $HTMLdir ] ; then
               echo "  Output directory $HTMLdir already exists"
               exit 1
           fi
           ;;
      k  )
           keepgoing="yes"
           echo "Will not stop if errors are encountered"
            ;;
      n  ) 
           notoc="--stringparam generate.toc ''"
           echo "Suppressing TOC..."
            ;;
      r  )
           RTFoutput="yes"
           echo "Producing RTF output rather than PDF"
            ;;
      \? ) 
           usage
           exit 1;;
  esac
done
shift $(($OPTIND - 1))

if [ ! -f $1 ] ; then
        echo "  Input file $1 not found - exiting."
        exit 
fi

В листинге 5 показана часть сценария, который использует приложение xmlto для генерирования HTML при формировании HTML-данных или приложение xsltproc для создания FO-данных из входного XML-файла при формировании PDF- или RTF-данных. Выходные данные преобразования XML в FO записываются во временный файл xsltproc.out, что упрощает отладку при обнаружении приложением xsltproc каких-либо ошибок в вашем входном файле. Если в этом файле имеется какая-либо ошибка, сценарий завершает работу после генерирования FO-файла. Затем можно проанализировать файл xsltproc.out, что поможет идентифицировать и решить проблему. Как и в листинге 4, можно также указать параметр командной строки -k для принудительного выполнения сценария даже после обнаружения ошибок во время обработки xsltproc.

Листинг 5. Генерирование FO-данных из входного XML-файла
doc_base=`basename $1 .xml`

echo "Processing base name: $doc_base"

if [ x$HTMLoutput != "xno" ] ; then
     xmlto -o $HTMLdir html $1
     exit
fi

echo "  Generating FO file:  $doc_base.fo"

$XSLTPROC --output $doc_base".fo" \
          --stringparam draft.mode $draft \
          --stringparam fop1.extensions 1 \
          --xinclude \
          $notoc \
          $driverfile \
          $1 1> xsltproc.out 2> xsltproc.out

probs=`grep -i error xsltproc.out | wc -l | sed -e 's; ;;g'`

if [ x$probs != "x0" ] ; then
          echo ""
          echo "PROBLEMS:"
          echo ""
          cat xsltproc.out
          echo ""
          if [ x$keepgoing = "xno" ] ; then
                  exit
          fi
fi

echo "    Fixing FO file references to system images..."
cat $doc_base".fo" | sed -e "s;\"url(\.\./external/;\"url($dir/\.\./external/;g" > $$
mv $$ $doc_base".fo"

В листинге 6 показан последний шаг сценария, в котором с помощью приложения fop из FO-файла генерируются PDF- или RTF-данные. Как и в процессе преобразования XML в FO, выходные данные шага преобразования FO в PDF/RTF записываются во временный файл fop.out, который упрощает отладку при обнаружении приложением fop ошибок в FO-файле. Если генерирование PDF/RTF завершается неудачно, можно проанализировать файл fop.out, чтобы идентифицировать и решить проблему. Как и в листинге 4, можно также указать параметр командной строки -k для принудительного выполнения сценария даже после обнаружения ошибок во время обработки xsltproc.

Листинг 6. Генерирование PDF- или RTF-данных из FO-файла
if [ x$RTFoutput = "xno" ] ; then
    echo "  Generating PDF file: $doc_base"".pdf"
        fop -fo $doc_base".fo" -pdf $doc_base".pdf" 1> fop.out 2> fop.out
else
    echo "  Generating RTF file: $doc_base"".rtf"
        fop -fo $doc_base".fo" -rtf $doc_base".rtf" 1> fop.out 2> fop.out
fi

probs=`grep -i Exception fop.out | wc -l | sed -e 's; ;;g'`

if [ x$probs != "x0" ] ; then
        echo ""
        echo "EXCEPTION OCCURRED DURING PROCESSING:"
        echo ""
        cat fop.out
        echo ""
fi

Можно загрузить копию этого примера сценария, называющегося xml-format.sh (см. файл xml-format.zip в разделе "Загрузка"). Для установки данного сценария на вашу систему загрузите zip-файл и извлеките xml-format.sh в каталог /home/doc/bin. Используйте следующую команду, чтобы обеспечить возможность выполнения сценария:

      chmod 755 /home/doc/bin/xml-format.sh

Наконец, убедитесь в том, что каталог /home/doc/bin имеется в пути исполнения, а если это не так, отредактируйте файл ~/.bashrc и добавьте в его конец следующую строку (либо выполните эту же строку в командной оболочке):

      export PATH=/home/doc/bin:${PATH}

При добавлении данной команды в файл ~/.bashrc активизируйте этот файл в текущем сеансе работы, чтобы изменения файла начали действовать в текущей командной оболочке. Для этого выполните следующую команду:

      source ~/.bashrc

Публикация DocBook-документа

Выполнение сценария xml-format.sh без аргументов отображает сводную информацию о том, как следует использовать сценарий (см. листинг 7).

Листинг 7. Выходная информация при выполнении сценария xml-format.sh без аргументов
      Usage: xml-format.sh [OPTIONS] document-name
        -D : produce draft mode document
        -d : use specified xsl driver (requires name of XSL file) 
        -h : generate HTML output (requires output directory name)
        -k : attempt PDF generation even if xsltproc errors were encountered
        -n : suppress TOC
        -r : produce RTF output rather than PDF

Для генерирования PDF-версии DocBook-документа просто выполните сценарий с названием этого документа, как показано в следующем примере:

      xml-format.sh sample-document.xml

Для генерирования HTML-версии DocBook-документа при помощи этого сценария необходимо использовать параметр -h и указать название каталога назначения для выходных HTML-файлов. Например, для создания HTML-версии DocBook-документа в каталоге HTML-output (относительно текущего рабочего каталога), выполните следующую команду:

      xml-format.sh -h HTML-output sample-document.xml

Добавление уровня настройки XSL для вывода PDF-данных

По умолчанию сценарий xml-format.sh, рассматриваемый в данной статье, использует таблицы стилей, поставляемые в пакете XSL DocBook. Для добавления своих собственных настроек можно создать таблицу стилей, которая сначала загружает таблицу стилей XSL DocBook по умолчанию, а затем предоставляет нужные значения для всех параметров, которые вы хотите переопределить. Пример уровня настройки приведен в таблице стилей generic-print-driver.xsl (см. файл generic-print-driver.zip в разделе "Загрузка").

Для использования другой таблицы стилей со сценарием xml-format.sh можно либо использовать параметр -d для указания полного или относительного пути к желаемой таблице стилей, либо изменить значение переменной driverfile в сценарии xml-format.sh. В пример сценария включена строка, разрешающая вам использовать пример сценария generic-print-driver.xsl. Просто закомментируйте предыдущее значение для переменной driverfile и снимите символы комментариев в следующей строке, содержащей новое определение.

Резюме

Мощность и гибкость XML, наличие стандартов и богатый набор инструментальных средств для работы с XML-документами и их преобразования позволяют легко создать и настроить ваш собственный набор программ для генерирования выходных данных в разных форматах из XML-документов. Хотя для редактирования и форматирования XML-документов существует множество коммерческих продуктов, создание своего собственного набора программ помогает лучше понять процесс и не тратить лишние средства.


Загрузка

ОписаниеИмяРазмер
Пример сценария форматирования DocBookxml-format.zip2 КБ
Пример настройки XSL для DocBookgeneric-print-driver.zip1 КБ

Ресурсы

Научиться

Получить продукты и технологии

  • Apache FOP. Загрузите последнюю версию для вашей платформы. Нажмите ссылку Download слева.(EN)
  • xsltproc. Загрузите последнюю версию для систем UNIX и Linux.(EN)
  • DocBook DTD. Загрузите последнюю версию и начните работать с ней.(EN)
  • DocBook XSL Stylesheets. Загрузите последнюю версию (перейдите на сайт DocBook Project site > file releases и выберите docbook-xsl).(EN)
  • xmlto. Загрузите последнюю версию, если ее еще нет на вашей системе. В зависимости от версии UNIX или Linux, возможно, понадобится загрузить и установить Bash, the Bourne-Again shell, GNU find and friends и mktemp.(EN)
  • IBM Java SDK. Загрузите этот комплект разработчика для вашей платформы. Возможно, на некоторых дистрибутивах UNIX и Linux понадобится загрузить и установить IBM Java SDK для использования программы форматирования Apache FOP.(EN)
  • Оценочные версии продуктов IBM. Загрузите или исследуйте в интерактивном режиме пробные продукты в IBM SOA Sandbox и осваивайте инструментальные средства разработки приложений и продукты промежуточного уровня DB2®, Lotus®, Rational®, Tivoli® и WebSphere®.

Обсудить

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=XML
ArticleID=458014
ArticleTitle=Подготовка документации и повторное использование информации в XML: Часть 1. Публикация документов с использованием XML
publish-date=12212009