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. Простые текстовые файлы #

Инструкции по установке также распространяются в виде обычного текста, на случай, если они понадобятся в ситуации, когда под рукой не окажется средств просмотра более удобного формата. Файл INSTALL соответствует Главе 17, с небольшими изменениями, внесёнными с учётом другого контекста. Чтобы пересоздать этот файл, перейдите в каталог doc/src/sgml и введите make INSTALL. Для получения текстового формата вам дополнительно потребуется Pandoc версии 1.13 или новее.

В прошлом примечания к выпуску и инструкции по регрессионному тестированию также распространялись в виде простых текстовых файлов, но эта практика была прекращена.

J.3.5. Проверка синтаксиса #

Сборка всей документации может занять много времени. Но если нужно проверить только синтаксис файлов документации, это можно сделать всего за несколько секунд:

doc/src/sgml$ make check