Файл: Коды ошибок Postgresql.docx

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

HTML

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

doc/src/sgml$ make html

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

Чтобы получить HTML-документацию со стилем оформления, используемым на сайте postgresql.org, вместо простого стандартного стиля, выполните:

doc/src/sgml$ make STYLE=website html

Страницы man

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

doc/src/sgml$ make man

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 ГБ) сборка либо будет слишком медленной из-за подкачки, либо вообще не будет осуществляться.

Также можно воспользоваться другими процессорами XSL-FO, запуская их вручную, но автоматическая процедура сборки поддерживает только FOP.

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

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

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

Проверка синтаксиса

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

doc/src/sgml$ make check

Написание документации

Форматы SGML и DocBook не страдают от обилия средств их редактирования с открытым исходным кодом. Чаще всего для написания документации используется редактор Emacs/XEmacs в подходящем режиме. В некоторых системах эти редакторы устанавливаются при типичной полной установке.

Emacs/PSGML

Режим PSGML — наиболее популярный и мощный режим редактирования документов SGML. При правильной настройке в Emacs он позволяет вставлять теги и проверять корректность разметки. Его также можно использовать для редактирования HTML. Загружаемые файлы, инструкции по установке и подробную документацию вы можете найти на сайте PSGML.

Необходимо отметить важный момент относительно PSGML: его автор предполагал, что вашим основным каталогом с DTD SGML будет /usr/local/lib/sgml. Если же у вас это каталог /usr/local/share/sgml, вам нужно дополнительно скорректировать предопределённый путь, либо воспользовавшись переменной окружения SGML_CATALOG_FILES, либо настроив соответственно вашу инсталляцию PSGML (как это сделать, можно узнать из его описания).

Поместите следующие строки в файл /.emacs (изменив пути на подходящие для вашей системы):

; ********** для режима SGML (psgml)

(setq sgml-omittag t)

(setq sgml-shorttag t)

(setq sgml-minimize-attributes nil)

(setq sgml-always-quote-attributes t)

(setq sgml-indent-step 1)

(setq sgml-indent-data t)

(setq sgml-parent-document nil)

(setq sgml-exposed-tags nil)

(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )

и добавьте в тот же файл запись для SGML в существующее определение auto-mode-alist:

(setq

auto-mode-alist

'(("\\.sgml$" . sgml-mode)

))

Используя PSGML, вы можете найти удобным вставлять подходящие объявления DOCTYPE в отдельные файлы книги, когда вы редактируете их. Например, редактируя текущий текст, который относится к главе приложений (appendix), вы можете обозначить документ как экземпляр документа «appendix», добавив в него следующую первую строку:

Это будет означать, что всё и вся, читающее этот SGML, сможет прочитать его правильно, и его корректность можно будет проверить командой nsgmls -s docguide.sgml. (Но вы должны будете убрать эту строку, прежде чем собирать весь комплект документации.)

Другие режимы Emacs.

GNU Emacs предлагает другой режим SGML, не такой мощный как PSGML, но при этом менее запутанный и тяжеловесный. Кроме того, в нём реализована подсветка синтаксиса (привязка шрифтов), которая бывает весьма полезна. Пример конфигурации для этого режима содержится в src/tools/editors/emacs.samples.

Норм Уолш предложил главный режим специально для DocBook, в котором также реализовал привязку шрифтов и ряд возможностей для оптимизации ввода текста.

Руководство по стилю.

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

Справочные страницы, описывающие исполняемые команды, должны содержать следующие разделы, в указанном порядке. Разделы, неуместные для данной команды, могут опускаться. Дополнительные разделы верхнего уровня могут использоваться только в особых случаях; часто эта информация помещается в раздел «Использование».

Название

Этот раздел генерируется автоматически. Он содержит имя команды и краткое (в полпредложения) описание её функциональности.

Синтаксис

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

Описание

Состоящее из нескольких абзацев описание действия команды.

Параметры

Список всех аргументов командной строки с описанием. Если аргументов очень много, их можно разделить на подразделы.

Код завершения

Если программа возвращает 0 в случае успеха и ненулевое значение при ошибке, описывать это не нужно. Если же различные ненулевые коды возврата имеют определённые значения, опишите их в этом разделе.

Использование

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

Переменные окружения

Список всех переменных окружения, которые может использовать эта программа. Постарайтесь сделать его полным — даже кажущиеся очевидными переменные вроде SHELL могут быть интересны пользователю.

Файлы

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

Диагностика

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

Замечания

Всё, что не подходит для других разделов, но особенно описание ошибок, недостатков реализации, соображения безопасности и вопросы совместимости.

Примеры

Примеры

История

Если в истории программы были значительные вехи, о них можно рассказать здесь. Обычно этот раздел можно опустить.

Автор

Автор (используется только в разделе внешних разработок (contrib))

См. также

Перекрёстные ссылки, перечисленные в следующем порядке: справочные страницы других команд PostgreSQL, справочные страницы SQL-команд PostgreSQL, цитаты из руководств PostgreSQL, другие справочные страницы (например, относящиеся к операционной системе и другим пакетам), другая документация. Пункты внутри одной группы перечисляются в алфавитном порядке.

Справочные страницы, описывающие команды SQL, должны содержать следующие разделы: Название, Синтаксис, Описание, Параметры, Результаты, Замечания, Примеры, Совместимость, История, См. также. Раздел «Параметры» похож на раздел «Аргументы» в описании исполняемых команд, но в нём можно выбирать, какие именно предложения команды описывать. Раздел «Результаты» может потребоваться, только если команда возвращает результат, отличный от стандартного тега завершения команды. В разделе «Совместимость» следует отметить, в какой степени описываемая команда соответствует стандарту SQL, или с какими другими СУБД она совместима. В разделе «См. также» следует привести ссылки на связанные команды SQL (до ссылок на команды).