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