J.3. Сборка документации
Пред. НаверхПриложение J. ДокументацияНачало След.

J.3. Сборка документации

J.3.1. HTML
J.3.2. Страницы man
J.3.3. Получение печатной версии с использованием JadeTeX
J.3.4. Переполнение текста
J.3.5. Получение печатной версии из RTF
J.3.6. Простые текстовые файлы
J.3.7. Проверка синтаксиса

Завершив все подготовительные действия, перейдите в каталог doc/src/sgml и запустите одну из команд сборки, описанных в следующих подразделах. (Помните, что для сборки нужно использовать GNU make.)

J.3.1. HTML

Чтобы собрать HTML-версию документации: 

doc/src/sgml$ make html

Эта цель сборки также выбирается по умолчанию. Результат помещается в подкаталог html.

Чтобы был сформирован алфавитный указатель, во время сборки требуется выполнить несколько проходов. Если этот указатель вам не нужен, вы просто хотите проверить результат, используйте режим draft: 

doc/src/sgml$ make draft

Чтобы получить документацию в виде одной HTML-страницы, выполните: 

doc/src/sgml$ make postgres.html

J.3.2. Страницы man

Для преобразования страниц DocBook refentry в формат *roff, подходящий для страниц man, мы используем стили DocBook XSL. Страницы man распространяются в архиве tar, подобно HTML-версии. Чтобы создать страницы man, выполните: 

cd doc/src/sgml
make man

J.3.3. Получение печатной версии с использованием JadeTeX

Если вы хотите получить печатную версию документации, используя JadeTex, вы можете воспользоваться одной из следующих команд:

  • Чтобы получить PostScript через DVI для формата A4, выполните: 

    doc/src/sgml$ make postgres-A4.ps

    Для формата «U.S. Letter» выполните: 

    doc/src/sgml$ make postgres-US.ps

  • Чтобы получить PDF: 

    doc/src/sgml$ make postgres-A4.pdf

    или: 

    doc/src/sgml$ make postgres-US.pdf

    (Разумеется, вы можете получить PDF и из PostScript, но если сгенерировать PDF напрямую, полученный файл будет содержать гиперссылки и другие расширенные особенности.)

Если вы намерены использовать JadeTeX для сборки документации PostgreSQL, вам, вероятно, потребуется увеличить некоторые внутренние параметры TeX. Их можно задать в файле texmf.cnf. На момент написания этого описания работали следующие параметры: 

hash_extra.jadetex  = 200000
hash_extra.pdfjadetex  = 200000
pool_size.jadetex = 2000000
pool_size.pdfjadetex = 2000000
string_vacancies.jadetex = 150000
string_vacancies.pdfjadetex = 150000
max_strings.jadetex = 300000
max_strings.pdfjadetex = 300000
save_size.jadetex = 15000
save_size.pdfjadetex = 15000

J.3.4. Переполнение текста

В некоторых местах текст документации оказывается слишком широким для предопределённых границ, и, в особых случаях, не умещается на странице. В частности, это наблюдается с широкими таблицами или текстом, не допускающим переносы. Сталкиваясь с такой ситуацией, TeX выводит сообщения «Overfull hbox» (Переполнение горизонтальной рамки) в файл журнала, например, postgres-US.log или postgres-A4.log. С учётом того, что дюйм составляют 72 точки, всё, что выходит за границу больше чем на 72 точки, скорее всего не поместится на печатаемой странице (при размере поля один дюйм). Чтобы найти в SGML текст, выходящий за границы, определите номер страницы, указанный над сообщением о переполнении, например: [50 ###] (стр. 50), и посмотрите на следующую страницу (в данном случае стр. 51) в PDF. Увидев, какой текст на ней выходит за границы, внесите требуемые коррективы в SGML.

J.3.5. Получение печатной версии из RTF

Вы также можете получить печатную версию документации PostgreSQL, преобразовав её в формат RTF, который позволяет откорректировать форматирование в офисном пакете. В зависимости от возможностей конкретного текстового редактора, затем документацию можно будет преобразовать в PostScript или PDF. Ниже описывается, как это можно проделать с применением Applixware.

Примечание

Судя по всему, текущие версии документации PostgreSQL провоцируют ошибку или превышают ограничения размера, существующие в OpenJade. Если у вас процесс сборки RTF «зависает» на долгое время, а размер выводимого файла остаётся нулевым, возможно, вы столкнулись именно с этой проблемой. (Но учтите, что обычная сборка занимает от 5 до 10 минут, так что не прерывайте процесс слишком быстро.)

Очистка RTF в Applixware

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

  1. Получите RTF-версию документации, введя: 

    doc/src/sgml$ make postgres.rtf

  2. Исправьте файл RTF, чтобы в нём корректно указывались все стили, в частности, стиль по умолчанию. Если документ содержит разделы refentry, нужно также заменить указания форматирования, связывающие предыдущий абзац с текущим, на указания, связывающие текущий абзац со следующим. Для внесения этих корректив предоставляется утилита fixrtf (она находится в doc/src/sgml): 

    doc/src/sgml$ ./fixrtf --refentry postgres.rtf

    Этот скрипт добавляет в документ {\s0 Normal;} в качестве нулевого стиля. По утверждению разработчиков Applixware, стандарт RTF не должен допускать добавления неявного нулевого стиля, хотя Microsoft Word обрабатывает это указание. Для исправления разделов refentry этот скрипт заменяет теги \keepn на \keep.

  3. Создайте новый документ в Applixware Words, а затем импортируйте в него файл RTF.

  4. Создайте оглавление с помощью Applixware.

    1. Выделите строки существующего оглавления, от первого символа первой строки до последнего символа последней строки.

    2. Постройте новое оглавление, выбрав в меню Tools → Book Building → Create Table of Contents (Сервис → Сборка книги → Создать оглавление). Выберите первые три уровня заголовков для включения в оглавление. В результате строки оглавления, импортированные из RTF, будут заменены оглавлением, созданным в Applixware.

    3. Поправьте форматирование оглавления, выбрав пункт меню Format → Style (Формат → Стиль), и определив следующие значения отступов (First (Первый) и Left (Слева)) для каждого из трёх стилей оглавления:

      СтильПервый отступ (в дюймах)Отступ слева (в дюймах)
      TOC-Heading 10.40.4
      TOC-Heading 20.80.8
      TOC-Heading 31.21.2

  5. Проработайте форматирование документа:

    • Расставьте разрывы страниц.

    • Поправьте ширину столбцов таблиц.

  6. Замените выравненные по правому краю номера страниц в части оглавления Примеры и Рисунки правильными значениями. Это должно занять всего несколько минут.

  7. Удалите из документа раздел алфавитного указателя, если он пуст.

  8. Сгенерируйте заново и скорректируйте оглавление.

    1. Выделите поле оглавления.

    2. Выберите в меню Tools → Book Building → Create Table of Contents (Сервис → Сборка книги → Создать оглавление).

    3. Отделите оглавление, выбрав в меню Tools → Field Editing → Unprotect (Сервис → Изменение полей → Снять защиту).

    4. Удалите первую строку в оглавлении, которая указывает на само оглавление.

  9. Сохраните документ в специальном формате Applixware Words, чтобы в него можно было легко внести последние правки.

  10. «Напечатайте» документ в файл формата PostScript.

J.3.6. Простые текстовые файлы

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

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

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

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

doc/src/sgml$ make check
Пред. Наверх След.
J.2. Инструментарий Начало J.4. Написание документации