J.2. Инструментарий
Для обработки документации применяются следующие средства. Некоторые из них могут быть необязательными, как отмечено ниже.
- DTD для DocBook
Это полное определение самого формата DocBook. В настоящее время мы применяем версию 4.2; более ранняя или более поздняя версия не подойдёт. Использовать нужно вариации SGML и XML формата DocBook этой же версии. Обычно они распространяются в отдельных пакетах.
- Сущности символов ISO 8879
Они требуются форматом DocBook SGML, но распространяются отдельно, так как поддерживаются комитетом ISO.
- Таблицы стилей DocBook XSL
Они содержат инструкции обработки для преобразования исходных материалов DocBook в другие форматы, например, в HTML.
На данный момент требуется версия как минимум 1.77.0, но для лучшего результата рекомендуется использовать последнюю доступную версию.
- OpenSP
Это базовый пакет для обработки SGML. Заметьте, что мы более не нуждаемся в OpenJade, процессоре DSSSL, а пакет OpenSP используем только для преобразования SGML в XML.
- Libxml2 для
xmllint Эта библиотека и включённая в неё утилита
xmllintприменяются для обработки XML. У многих разработчиков библиотека Libxml2 уже установлена, потому что она также используются при сборке кода PostgreSQL. Заметьте, однако, чтоxmllintможет потребоваться установить из отдельного пакета.- Libxslt для
xsltproc xsltproc— процессор XSLT, то есть программа, преобразующая XML в другие форматы с применением таблиц стилей XSLT.- FOP
Это программа для преобразования, в том числе и XML в PDF.
Ниже мы опишем различные варианты установки программного обеспечения, необходимого для обработки документации. Эти программы могут распространяться и в других пакетах. Пожалуйста, сообщите о состоянии конкретного пакета в список рассылки, посвящённый документации, и мы добавим эту информацию сюда.
Вы можете обойтись без локальной установки файлов DocBook XML и таблиц стилей DocBook XSLT, так как необходимые файлы будут загружены из Интернета и помещены в локальный кеш. Этот вариант на самом деле может быть предпочтительным, если в пакетах вашей операционной системы предоставляются только старые версии файлов (особенно стилей) или если таких пакетов нет вовсе. Дополнительную информацию вы можете получить, ознакомившись с параметром --nonet программ xmllint и xsltproc.
J.2.1. Установка в Fedora, RHEL и производных системах
Чтобы установить требуемые пакеты, выполните:
yum install docbook-dtds docbook-style-xsl fop libxslt opensp
J.2.2. Установка во FreeBSD
Проект документации FreeBSD сам активно использует DocBook, поэтому неудивительно, что для FreeBSD есть полный набор «портов» инструментария для сборки документации. Чтобы собирать документацию во FreeBSD, необходимо установить нижеперечисленные порты.
textproc/docbook-sgmltextproc/docbook-xmltextproc/docbook-xsltextproc/dsssl-docbook-modulartextproc/libxslttextproc/foptextproc/opensp
Чтобы установить требуемые пакеты, используя pkg, выполните:
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
Собирая документацию из каталога doc, вы должны применять gmake, так как существующий Makefile не подходит для make, имеющегося во FreeBSD.
Дополнительные сведения об инструментарии документации FreeBSD можно найти в инструкциях проекта документации FreeBSD.
J.2.3. Пакеты Debian
Для Debian GNU/Linux имеется полный набор пакетов инструментария сборки документации. Чтобы установить их, просто выполните:
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc
J.2.4. macOS
Если вы используете систему MacPorts, вы можете получить необходимое программное обеспечение так:
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp
J.2.5. Установка из исходного кода вручную
Процесс установки инструментария DocBook довольно сложен, поэтому, если для вашей системы есть готовые пакеты, используйте их. Мы опишем здесь только стандартную процедуру с обычными путями инсталляции и без «экстраординарных» функций. За подробностями вы можете обратиться к документации соответствующего пакета или вводному материалу по SGML.
J.2.5.1. Установка OpenSP
Установка OpenSP заключается в процессе сборки в стиле GNU ./configure; make; make install. Подробности можно найти в пакете исходного кода OpenJade. Вкратце:
./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install
Обязательно запомните, какой путь вы задали для «каталога по умолчанию»; он понадобится вам позже. Вы можете и не задавать его, но тогда вам надо будет устанавливать путь к каталогу в переменной окружения SGML_CATALOG_FILES всякий раз, когда вы будете использовать программы из OpenSP. (Это может пригодиться, если OpenSP уже установлен и вы хотите установить остальные компоненты локально.)
J.2.5.2. Установка DocBook DTD
Получите пакет 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.)
J.2.6. Проверка условий configure
Прежде чем вы сможете собрать документацию, вы должны запустить скрипт configure так же, как это нужно сделать для сборки программной части PostgreSQL. Обратите внимание на сообщения, выводимые ближе к концу. Вы должны увидеть примерно следующее:
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, или не настроили корректно файлы каталогов. Прочитайте приведённые выше указания по установке.