J.2. Инструментарий #
Для обработки документации применяются следующие средства. Некоторые из них могут быть необязательными, как отмечено ниже.
- DTD для DocBook #
Это полное определение самого формата DocBook. В настоящее время мы применяем версию 4.5; более ранняя или более поздняя версия не подойдёт. Использовать нужно XML-вариацию определения DocBook DTD (не SGML).
- Таблицы стилей DocBook XSL #
Они содержат инструкции обработки для преобразования исходных материалов DocBook в другие форматы, например, в HTML.
На данный момент требуется версия как минимум 1.77.0, но для лучшего результата рекомендуется использовать последнюю доступную версию.
- Libxml2 для
xmllint# Эта библиотека и включённая в неё утилита
xmllintприменяются для обработки XML. У многих разработчиков библиотека Libxml2 уже установлена, потому что она также используются при сборке кода PostgreSQL. Заметьте, однако, чтоxmllintможет потребоваться установить из отдельного пакета.- Libxslt для
xsltproc# xsltproc— процессор XSLT, то есть программа, преобразующая XML в другие форматы с применением таблиц стилей XSLT.- FOP #
Это программа для преобразования, в том числе и XML в PDF. Она требуется только для сборки документации в формате PDF.
Ниже мы опишем различные варианты установки программного обеспечения, необходимого для обработки документации. Эти программы могут распространяться и в других пакетах. Пожалуйста, сообщите о состоянии конкретного пакета в список рассылки, посвящённый документации, и мы добавим эту информацию сюда.
J.2.1. Установка в Fedora, RHEL и производных системах #
Чтобы установить требуемые пакеты, выполните:
yum install docbook-dtds docbook-style-xsl libxslt fop
J.2.2. Установка во FreeBSD #
Чтобы установить требуемые пакеты, используя pkg, выполните:
pkg install docbook-xml docbook-xsl libxslt fop
Собирая документацию из каталога doc, вы должны применять gmake, так как существующий Makefile не подходит для make, имеющегося во FreeBSD.
J.2.3. Пакеты Debian #
Для Debian GNU/Linux имеется полный набор пакетов инструментария сборки документации. Чтобы установить их, просто выполните:
apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
J.2.4. macOS #
Если вы используете систему MacPorts, вы можете получить всё необходимое так:
sudo port install docbook-xml docbook-xsl-nons libxslt fop
Если вы используете Homebrew, выполните:
brew install docbook docbook-xsl libxslt fop
Для программ, устанавливаемых с помощью Homebrew, требуется установить следующую переменную среды. Для компьютеров на базе Intel:
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
Для компьютеров на базе Apple Silicon:
export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
Без этой переменной xsltproc будет выдавать такие ошибки:
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" ...
Хотя можно использовать версии xmllint и xsltproc от Apple вместо версий от MacPorts или Homebrew, вам всё равно потребуется установить DocBook DTD и стили, а также настроить файл каталога, который будет на них указывать.
J.2.5. Проверка условий 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 ...
Если вы предпочитаете собирать PostgreSQL с помощью Meson, вместо этого запустите meson setup, как описано в Разделе 17.4, а затем обратитесь к Разделу J.4.