J.2. Инструментарий
Для обработки документации применяются следующие средства. Некоторые из них могут быть необязательными, как отмечено ниже.
- DTD для DocBook
Это полное определение самого формата DocBook. В настоящее время мы применяем версию 4.2; более ранняя или более поздняя версия не подойдёт. Использовать нужно 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 ...
J.2. Tool Sets
The following tools are used to process the documentation. Some might be optional, as noted.
- DocBook DTD
This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. You need the XML variant of the DocBook DTD, not the SGML variant.
- DocBook XSL Stylesheets
These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.
The minimum required version is currently 1.77.0, but it is recommended to use the latest available version for best results.
- Libxml2 for
xmllint This library and the
xmllinttool it contains are used for processing XML. Many developers will already have Libxml2 installed, because it is also used when building the PostgreSQL code. Note, however, thatxmllintmight need to be installed from a separate subpackage.- Libxslt for
xsltproc xsltprocis an XSLT processor, that is, a program to convert XML to other formats using XSLT stylesheets.- FOP
This is a program for converting, among other things, XML to PDF. It is needed only if you want to build the documentation in PDF format.
We have documented experience with several installation methods for the various tools that are needed to process the documentation. These will be described below. There might be some other packaged distributions for these tools. Please report package status to the documentation mailing list, and we will include that information here.
J.2.1. Installation on Fedora, RHEL, and Derivatives
To install the required packages, use:
yum install docbook-dtds docbook-style-xsl libxslt fop
J.2.2. Installation on FreeBSD
To install the required packages with pkg, use:
pkg install docbook-xml docbook-xsl libxslt fop
When building the documentation from the doc directory you'll need to use gmake, because the makefile provided is not suitable for FreeBSD's make.
J.2.3. Debian Packages
There is a full set of packages of the documentation tools available for Debian GNU/Linux. To install, simply use:
apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
J.2.4. macOS
If you use MacPorts, the following will get you set up:
sudo port install docbook-xml docbook-xsl-nons libxslt fop
If you use Homebrew, use this:
brew install docbook docbook-xsl libxslt fop
The Homebrew-supplied programs require the following environment variable to be set. For Intel based machines, use this:
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
On Apple Silicon based machines, use this:
export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
Without it, xsltproc will throw errors like this:
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" ...
While it is possible to use the Apple-provided versions of xmllint and xsltproc instead of those from MacPorts or Homebrew, you'll still need to install the DocBook DTD and stylesheets, and set up a catalog file that points to them.
J.2.5. Detection by configure
Before you can build the documentation you need to run the configure script, as you would when building the PostgreSQL programs themselves. Check the output near the end of the run; it should look something like this:
checking for xmllint... xmllint checking for xsltproc... xsltproc checking for fop... fop checking for dbtoepub... dbtoepub
If xmllint or xsltproc is not found, you will not be able to build any of the documentation. fop is only needed to build the documentation in PDF format. dbtoepub is only needed to build the documentation in EPUB format.
If necessary, you can tell configure where to find these programs, for example
./configure ... XMLLINT=/opt/local/bin/xmllint ...
