Для обработки документации применяются следующие средства. Некоторые из них могут быть необязательными, как отмечено ниже.
Это полное определение самого формата DocBook. В настоящее время мы применяем версию 4.5; более ранняя или более поздняя версия не подойдёт. Использовать нужно 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.5 docbook-xsl fop
Если вы используете Homebrew, выполните:
brew install docbook docbook-xsl fop
configureПрежде чем вы сможете собрать документацию, вы должны запустить скрипт configure так же, как это нужно сделать для сборки программной части PostgreSQL. Обратите внимание на сообщения, выводимые ближе к концу. Вы должны увидеть примерно следующее:
checking for xmllint... xmllint checking for DocBook XML V4.5... yes checking for dbtoepub... dbtoepub checking for xsltproc... xsltproc checking for fop... fop
Если программа xmllint не будет обнаружена, часть следующих тестов будет пропущена.