Для обработки документации применяются следующие средства. Некоторые из них могут быть необязательными, как отмечено ниже.
Это полное определение самого формата DocBook. В настоящее время мы применяем версию 4.2; более ранняя или более поздняя версия не подойдёт. Использовать нужно XML-вариацию определения DocBook DTD (не SGML).
Они содержат инструкции обработки для преобразования исходных материалов DocBook в другие форматы, например, в HTML.
На данный момент требуется версия как минимум 1.77.0, но для лучшего результата рекомендуется использовать последнюю доступную версию.
xmllintЭта библиотека и включённая в неё утилита xmllint применяются для обработки XML. У многих разработчиков библиотека Libxml2 уже установлена, потому что она также используются при сборке кода PostgreSQL. Заметьте, однако, что xmllint может потребоваться установить из отдельного пакета.
xsltprocxsltproc — процессор XSLT, то есть программа, преобразующая XML в другие форматы с применением таблиц стилей XSLT.
Это программа для преобразования, в том числе и XML в PDF.
Ниже мы опишем различные варианты установки программного обеспечения, необходимого для обработки документации. Эти программы могут распространяться и в других пакетах. Пожалуйста, сообщите о состоянии конкретного пакета в список рассылки, посвящённый документации, и мы добавим эту информацию сюда.
Вы можете обойтись без локальной установки файлов DocBook XML и таблиц стилей DocBook XSLT, так как необходимые файлы будут загружены из Интернета и помещены в локальный кеш. Этот вариант на самом деле может быть предпочтительным, если в пакетах вашей операционной системы предоставляются только старые версии этих файлов или если таких пакетов нет вовсе. Если вы хотите предотвратить обращения к Интернету в процессе сборке документации, передайте параметр --nonet программам xmllint и xsltproc; см. пример ниже.
Чтобы установить требуемые пакеты, выполните:
yum install docbook-dtds docbook-style-xsl fop libxslt
Чтобы установить требуемые пакеты, используя pkg, выполните:
pkg install docbook-xml docbook-xsl fop libxslt
Собирая документацию из каталога doc, вы должны применять gmake, так как существующий Makefile не подходит для make, имеющегося во FreeBSD.
Для Debian GNU/Linux имеется полный набор пакетов инструментария сборки документации. Чтобы установить их, просто выполните:
apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
В macOS вы можете сформировать документацию в форматах HTML и man, не устанавливая ничего дополнительно. Если вы хотите сформировать PDF или установить локальную копию DocBook, всё необходимое для этого можно получить с помощью менеджера пакетов.
Если вы используете систему MacPorts, вы можете получить всё необходимое так:
sudo port install docbook-xml-4.2 docbook-xsl fop
Если вы используете Homebrew, выполните:
brew install docbook docbook-xsl fop
configureПрежде чем вы сможете собрать документацию, вы должны запустить скрипт configure так же, как это нужно сделать для сборки программной части PostgreSQL. Обратите внимание на сообщения, выводимые ближе к концу. Вы должны увидеть примерно следующее:
checking for xmllint... xmllint checking for xsltproc... xsltproc checking for fop... fop checking for dbtoepub... dbtoepub
Если программа xmllint или xsltproc не будет обнаружена, вы не сможете собрать документацию в каком-либо виде. Программа fop требуется только для сборки документации в формате PDF, а dbtoepub нужна только для формата EPUB.
При необходимости вы можете указать configure, где найти эти программы, например так:
./configure ... XMLLINT=/opt/local/bin/xmllint ...
Кроме того, если нужно, чтобы программы xmllint и xsltproc не обращались к сети, это можно сделать так:
./configure ... XMLLINT="xmllint --nonet" XSLTPROC="xsltproc --nonet" ...