J.3. Сборка документации с помощью Make #
Завершив все подготовительные действия, перейдите в каталог doc/src/sgml и запустите одну из команд сборки, описанных в следующих подразделах. (Помните, что для сборки нужно использовать GNU make.)
J.3.1. HTML #
Чтобы собрать HTML-версию документации:
doc/src/sgml$make html
Эта цель сборки также выбирается по умолчанию. Результат помещается в подкаталог html.
Чтобы получить HTML-документацию со стилем оформления, используемым на сайте postgresql.org, вместо простого стандартного стиля, выполните:
doc/src/sgml$make STYLE=website html
В случае использования указания STYLE=website создаваемые HTML-файлы будут ссылаться на стили, размещённые на сайте postgresql.org, и для просмотра этих файлов потребуется доступ к сети.
J.3.2. Страницы man #
Для преобразования страниц DocBook refentry в формат *roff, подходящий для страниц man, мы используем стили DocBook XSL. Чтобы создать страницы man, выполните команду:
doc/src/sgml$make man
J.3.3. PDF #
Чтобы получить документацию в формате PDF, используя FOP, выполните одну из следующих команд, в зависимости от предпочитаемого размера бумаги:
Для формата A4:
doc/src/sgml$make postgres-A4.pdfДля формата U.S. letter:
doc/src/sgml$make postgres-US.pdf
Так как документация PostgreSQL весьма объёмна, процессору FOP для её обработки требуется много памяти. Поэтому в некоторых системах сборка может прерваться ошибкой, связанной с памятью. Обычно это можно исправить, увеличив объём области кучи Java в файле конфигурации ~/.foprc, например:
# Бинарный пакет FOP FOP_OPTS='-Xmx1500m' # Debian JAVA_ARGS='-Xmx1500m' # Red Hat ADDITIONAL_FLAGS='-Xmx1500m'
Некоторый объём памяти является минимально необходимым, а если задать больший объём, возможно даже некоторое ускорение сборки. В системах с очень маленьким объёмом памяти (меньше 1 ГБ) сборка либо будет слишком медленной из-за подкачки, либо вообще не будет осуществляться.
В конфигурации по умолчанию FOP выдаёт сообщение INFO для каждой страницы. Уровень детализации можно изменить в файле конфигурации ~/.foprc:
LOGCHOICE=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
Также можно воспользоваться другими процессорами XSL-FO, запуская их вручную, но автоматическая процедура сборки поддерживает только FOP.
J.3.4. Проверка синтаксиса #
Сборка всей документации может занять много времени. Но если нужно проверить только синтаксис файлов документации, это можно сделать всего за несколько секунд:
doc/src/sgml$make check
J.3. Building the Documentation with Make #
Once you have everything set up, change to the directory doc/src/sgml and run one of the commands described in the following subsections to build the documentation. (Remember to use GNU make.)
J.3.1. HTML #
To build the HTML version of the documentation:
doc/src/sgml$make html
This is also the default target. The output appears in the subdirectory html.
To produce HTML documentation with the stylesheet used on postgresql.org instead of the default simple style use:
doc/src/sgml$make STYLE=website html
If the STYLE=website option is used, the generated HTML files include references to stylesheets hosted on postgresql.org and require network access to view.
J.3.2. Manpages #
We use the DocBook XSL stylesheets to convert DocBook refentry pages to *roff output suitable for man pages. To create the man pages, use the command:
doc/src/sgml$make man
J.3.3. PDF #
To produce a PDF rendition of the documentation using FOP, you can use one of the following commands, depending on the preferred paper format:
For A4 format:
doc/src/sgml$make postgres-A4.pdfFor U.S. letter format:
doc/src/sgml$make postgres-US.pdf
Because the PostgreSQL documentation is fairly big, FOP will require a significant amount of memory. Because of that, on some systems, the build will fail with a memory-related error message. This can usually be fixed by configuring Java heap settings in the configuration file ~/.foprc, for example:
# FOP binary distribution FOP_OPTS='-Xmx1500m' # Debian JAVA_ARGS='-Xmx1500m' # Red Hat ADDITIONAL_FLAGS='-Xmx1500m'
There is a minimum amount of memory that is required, and to some extent more memory appears to make things a bit faster. On systems with very little memory (less than 1 GB), the build will either be very slow due to swapping or will not work at all.
In its default configuration FOP will emit an INFO message for each page. The log level can be changed via ~/.foprc:
LOGCHOICE=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
Other XSL-FO processors can also be used manually, but the automated build process only supports FOP.
J.3.4. Syntax Check #
Building the documentation can take very long. But there is a method to just check the correct syntax of the documentation files, which only takes a few seconds:
doc/src/sgml$make check