Для обработки документации применяются следующие средства. Некоторые из них могут быть необязательными, как отмечено ниже.
Это полное определение самого формата DocBook. В настоящее время мы применяем версию 4.2; более ранняя или более поздняя версия не подойдёт. Использовать нужно вариации SGML и XML формата DocBook этой же версии. Обычно они распространяются в отдельных пакетах.
Они требуются форматом DocBook SGML, но распространяются отдельно, так как поддерживаются комитетом ISO.
Они содержат инструкции обработки для преобразования исходных материалов DocBook в другие форматы, например, в HTML.
На данный момент требуется версия как минимум 1.77.0, но для лучшего результата рекомендуется использовать последнюю доступную версию.
Это базовый пакет для обработки SGML. Заметьте, что мы более не нуждаемся в OpenJade, процессоре DSSSL, а пакет OpenSP используем только для преобразования SGML в XML.
xmllintЭта библиотека и включённая в неё утилита xmllint применяются для обработки XML. У многих разработчиков библиотека Libxml2 уже установлена, потому что она также используются при сборке кода Postgres Pro. Заметьте, однако, что xmllint может потребоваться установить из отдельного пакета.
xsltprocxsltproc — процессор XSLT, то есть программа, преобразующая XML в другие форматы с применением таблиц стилей XSLT.
Это программа для преобразования, в том числе и XML в PDF.
Ниже мы опишем различные варианты установки программного обеспечения, необходимого для обработки документации. Эти программы могут распространяться и в других пакетах. Пожалуйста, сообщите о состоянии конкретного пакета в список рассылки, посвящённый документации, и мы добавим эту информацию сюда.
Вы можете обойтись без локальной установки файлов DocBook XML и таблиц стилей DocBook XSLT, так как необходимые файлы будут загружены из Интернета и помещены в локальный кеш. Этот вариант на самом деле может быть предпочтительным, если в пакетах вашей операционной системы предоставляются только старые версии файлов (особенно стилей) или если таких пакетов нет вовсе. Дополнительную информацию вы можете получить, ознакомившись с параметром --nonet программ xmllint и xsltproc.
Чтобы установить требуемые пакеты, выполните:
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
Проект документации FreeBSD сам активно использует DocBook, поэтому неудивительно, что для FreeBSD есть полный набор «портов» инструментария для сборки документации. Чтобы собирать документацию во FreeBSD, необходимо установить нижеперечисленные порты.
textproc/docbook-sgml
textproc/docbook-xml
textproc/docbook-xsl
textproc/dsssl-docbook-modular
textproc/libxslt
textproc/fop
textproc/opensp
Чтобы установить требуемые пакеты, используя pkg, выполните:
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
Собирая документацию из каталога doc, вы должны применять gmake, так как существующий Makefile не подходит для make, имеющегося во FreeBSD.
Дополнительные сведения об инструментарии документации FreeBSD можно найти в инструкциях проекта документации FreeBSD.
Для Debian GNU/Linux имеется полный набор пакетов инструментария сборки документации. Чтобы установить их, просто выполните:
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
Если вы используете систему MacPorts, вы можете получить необходимое программное обеспечение так:
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
Процесс установки инструментария DocBook довольно сложен, поэтому, если для вашей системы есть готовые пакеты, используйте их. Мы опишем здесь только стандартную процедуру с обычными путями инсталляции и без «экстраординарных» функций. За подробностями вы можете обратиться к документации соответствующего пакета или вводному материалу по SGML.
Установка OpenSP заключается в процессе сборки в стиле GNU ./configure; make; make install. Подробности можно найти в пакете исходного кода OpenJade. Вкратце:
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install
Обязательно запомните, какой путь вы задали для «каталога по умолчанию»; он понадобится вам позже. Вы можете и не задавать его, но тогда вам надо будет устанавливать путь к каталогу в переменной окружения SGML_CATALOG_FILES всякий раз, когда вы будете использовать программы из OpenSP. (Это может пригодиться, если OpenSP уже установлен и вы хотите установить остальные компоненты локально.)
Получите пакет DocBook V4.2.
Создайте каталог /usr/local/share/sgml/docbook-4.2 и перейдите в него. (Расположение может быть и другим, но данный путь соответствует структуре каталогов, которой мы следуем здесь.)
$mkdir /usr/local/share/sgml/docbook-4.2$cd /usr/local/share/sgml/docbook-4.2
Распакуйте архив:
$unzip -a ...../docbook-4.2.zip
(Файлы архива будут распакованы в текущий каталог.)
Отредактируйте файл /usr/local/share/sgml/catalog (или тот, что был указан при инсталляции jade) и добавьте в него такую строку:
CATALOG "docbook-4.2/docbook.cat"
Загрузите архив сущностей символов ISO 8879, распакуйте его и поместите файлы в тот же каталог, в который вы поместили файлы DocBook:
$cd /usr/local/share/sgml/docbook-4.2$unzip ...../ISOEnts.zip
Запустите в каталоге с файлами DocBook и ISO следующую команду:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(Она исправляет несоответствие имён в файле каталога DocBook и фактических имён файлов сущностей ISO.)
configureПрежде чем вы сможете собрать документацию, вы должны запустить скрипт configure так же, как это нужно сделать для сборки программной части Postgres Pro. Обратите внимание на сообщения, выводимые ближе к концу. Вы должны увидеть примерно следующее:
checking for onsgmls... onsgmls
checking for DocBook V4.2... yes
checking for dbtoepub... dbtoepub
checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for osx... osx
checking for fop... fop
Если ни onsgmls, ни nsgmls не будут найдены, некоторые из следующих тестов будут пропущены. Программа nsgmls входит в состав пакета OpenSP. Вы можете передать configure в переменной окружения NSGMLS путь к этим программам, если они не находятся автоматически. Если «DocBook V4.2» не находится, значит вы не установили файлы DocBook DTD туда, где их может найти OpenSP, или не настроили корректно файлы каталогов. Прочитайте приведённые выше указания по установке.