| Документация по PostgreSQL 9.4.1 | |||
|---|---|---|---|
| Пред. | Уровень выше | Приложение I. Документация | След. |
I.2. Инструментарий
Для обработки документации применяются следующие средства. Некоторые из них могут быть необязательными, как отмечено ниже.
- DTD для DocBook
Это полное определение самого формата DocBook. В настоящее время мы применяем версию 4.2; более ранняя или более поздняя версия не подойдёт. Использовать нужно вариант SGML формата DocBook, но для сборки страниц man вам также потребуется вариант XML той же версии.
- Сущности символов ISO 8879
Они требуются форматом DocBook, но распространяются отдельно, так как поддерживаются комитетом ISO.
- Таблицы стилей DocBook DSSSL
Они содержат инструкции обработки для преобразования исходных материалов DocBook в другие форматы, например, в HTML.
- Таблицы стилей DocBook XSL
Это ещё одни стили для преобразования DocBook в другие форматы. В настоящее время мы используем их для получения страниц man и дополнительного формата, HTMLHelp. Эти стили можно применять и для получения вывода в HTML или PDF, но в официальных выпусках PostgreSQL для этого используются стили DSSSL.
На данный момент требуется версия как минимум 1.74.0.
- OpenJade
Это базовый пакет для обработки SGML. В него входит средство разбора SGML, процессор DSSSL (то есть программа, преобразующая SGML в другие форматы, применяя стили DSSSL), а также ряд связанных инструментов. Поддержкой Jade теперь занимается не Джеймс Кларк, а группа OpenJade.
- Libxslt для xsltproc
Это средство преобразования с применением стилей XSLT (как jade — средство преобразования с применением стилей DSSSL).
- JadeTeX
Если хотите, вы также можете установить JadeTeX, чтобы использовать TeX как модуль форматирования для Jade. JadeTeX может создавать файлы PostScript и PDF (последние с закладками).
Однако вывод JadeTeX уступает тому, что можно получить через RTF. В частности, проблемы возникают с таблицами, а также с горизонтальными и вертикальными отступами. Кроме того, при таком выводе нет возможности вручную отполировать результаты.
Ниже мы опишем различные варианты установки программного обеспечения, необходимого для обработки документации. Эти программы могут распространяться и в других пакетах. Пожалуйста, сообщите о состоянии конкретного пакета в список рассылки, посвящённый документации, и мы добавим эту информацию сюда.
I.2.1. Установка RPM в Linux
Многие производители включают полный набор RPM-пакетов для обработки DocBook в состав своих дистрибутивов. Поищите пункт "SGML" в инсталляторе системы, либо следующие имена пакетов: sgml-common, docbook, stylesheets, openjade (или jade). Вам также могут понадобиться sgml-tools и либо xsltproc, либо libxslt. Если ваш поставщик ОС не предоставляет эти пакеты, вы, скорее всего, сможете воспользоваться совместимыми пакетами другого поставщика.
I.2.2. Установка во FreeBSD
Проект документации FreeBSD сам активно использует DocBook, поэтому неудивительно, что для FreeBSD есть полный набор "портов" инструментария для сборки документации. Чтобы собирать документацию во FreeBSD, необходимо установить нижеперечисленные порты.
textproc/sp
textproc/openjade
textproc/iso8879
textproc/dsssl-docbook-modular
textproc/docbook-420
Также могут представлять интерес некоторые вещи из /usr/ports/print (tex, jadetex).
Возможна ситуация, когда порты не обновляют основной файл каталога в /usr/local/share/sgml/catalog.ports или их порядок оказывается некорректным. Убедитесь, что в начале этого файла имеются следующие строки:
CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog"
Если вы не хотите редактировать этот файл, вы также можете задать в переменной окружения SGML_CATALOG_FILES список разделённых двоеточием файлов каталогов (перечисленных выше).
Дополнительные сведения об инструментарии документации FreeBSD можно найти в инструкциях проекта документации FreeBSD.
I.2.3. Пакеты Debian
Для Debian GNU/Linux имеется полный набор пакетов инструментария сборки документации. Чтобы установить их, просто выполните:
apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 opensp xsltproc
I.2.4. OS X
Если вы используете систему MacPorts, вы можете получить необходимое программное обеспечение так:
sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp
I.2.5. Установка из исходного кода вручную
Процесс установки инструментария DocBook довольно сложен, поэтому, если для вашей системы есть готовые пакеты, используйте их. Мы опишем здесь только стандартную процедуру с обычными путями инсталляции и без "экстраординарных" функций. За подробностями вы можете обратиться к документации соответствующего пакета или вводному материалу по SGML.
I.2.5.1. Установка OpenJade
Установка OpenJade заключается в процессе сборки в стиле GNU ./configure; make; make install. Подробности можно найти в пакете исходного кода OpenJade. Вкратце:
./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install
Обязательно запомните, какой путь вы задали для "каталога по умолчанию"; он понадобится вам позже. Вы можете и не задавать его, но тогда вам надо будет устанавливать путь к каталогу в переменной окружения SGML_CATALOG_FILES всякий раз, когда вы будете использовать jade. (Это может пригодиться, если OpenJade уже установлен и вы хотите установить остальные компоненты локально.)
Замечание: Некоторые пользователи сообщали о возникновении ошибки сегментации в OpenJade 1.4devel при попытке сгенерировать PDF, с таким сообщением:
openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted make: *** [postgres-A4.tex-pdf] Segmentation fault
Понижение версии OpenJade до 1.3 должно решить эту проблему.
Кроме того, вы должны установить файлы dsssl.dtd, fot.dtd, style-sheet.dtd и catalog из каталога dsssl в определённое место, возможно, в /usr/local/share/sgml/dsssl. Вероятно, проще всего для этого будет скопировать весь каталог:
cp -R dsssl /usr/local/share/sgml
Наконец, создайте файл /usr/local/share/sgml/catalog и добавьте в него эту строку:
CATALOG "dsssl/catalog"
(Это ссылка по относительному пути на файл, установленный на Шаге 2. Обязательно скорректируйте этот путь, если ваша инсталляция имеет другую структуру.)
I.2.5.2. Установка DocBook DTD
Получите пакет DocBook V4.2.
Создайте каталог /usr/local/share/sgml/docbook-4.2 и перейдите в него. (Расположение может быть и другим, но данный путь соответствует структуре каталогов, которой мы следуем здесь.)
$ mkdir /usr/local/share/sgml/docbook-4.2 $ cd /usr/local/share/sgml/docbook-4.2
Распакуйте архив:
$ unzip -a ...../docbook-4.2.zip
(Файлы архива будут распакованы в текущий каталог.)
Отредактируйте файл /usr/local/share/sgml/catalog (или тот, что был указан при инсталляции jade) и добавьте в него такую строку:
CATALOG "docbook-4.2/docbook.cat"
Загрузите архив сущностей символов ISO 8879, распакуйте его и поместите файлы в тот же каталог, в который вы поместили файлы DocBook:
$ cd /usr/local/share/sgml/docbook-4.2 $ unzip ...../ISOEnts.zip
Запустите в каталоге с файлами DocBook и ISO следующую команду:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(Она исправляет несоответствие имён в файле каталога DocBook и фактических имён файлов сущностей ISO.)
I.2.5.3. Установка таблиц стилей DocBook DSSSL
Чтобы установить таблицы стилей, разархивируйте дистрибутивный пакет и поместите его содержимое в подходящее место, например, в /usr/local/share/sgml. (Из архива будет автоматически извлечён подкаталог.)
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
Также можно добавить обычную запись в каталог /usr/local/share/sgml/catalog:
CATALOG "docbook-dsssl-1.xx/catalog"
Так как таблицы стилей меняются довольно часто и иногда имеет смысл использовать альтернативные версии, документация PostgreSQL не использует эту запись каталога. Как выбрать таблицы стилей для неё, описано в Подразделе I.2.6.
I.2.5.4. Установка JadeTeX
Чтобы установить и использовать JadeTeX, вам потребуется рабочая инсталляция TeX и LaTeX2e, включающая: поддерживаемые пакеты tools и graphics, шрифты Babel, AMS и AMS-LaTeX, расширение PSNFSS, дополнительный набор из "35 шрифтов", программу dvips для вывода в PostScript, а также пакеты макросов fancyhdr, hyperref, minitoc, url и ot2enc. Все эти компоненты можно найти на родственном сайте CTAN. Рассмотрение установки базовой системы TeX выходит далеко за рамки этого введения. Для любой системы, в которой может работать TeX, должны существовать и готовые двоичные пакеты.
Прежде чем использовать JadeTeX с исходным материалом документации PostgreSQL, вам необходимо увеличить размер внутренних структур данных TeX. Подробнее об этом рассказывается в инструкциях по установке JadeTeX.
Выполнив необходимые условия, вы можете установить JadeTeX так:
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
Последние две команды нужно выполнять от имени root.
I.2.6. Проверка условий configure
Прежде чем вы сможете собрать документацию, вы должны запустить скрипт configure так же, как это нужно сделать для сборки программной части PostgreSQL. Обратите внимание на сообщения, выводимые ближе к концу. Вы должны увидеть примерно следующее:
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular checking for collateindex.pl... /usr/bin/collateindex.pl checking for xsltproc... xsltproc checking for osx... osx
Если ни onsgmls, ни nsgmls не будут найдены, некоторые из следующих тестов будут пропущены. Программа nsgmls входит в состав пакета Jade. Вы можете передать configure в переменных окружения JADE и NSGMLS пути к соответствующим программам, если они не находятся автоматически. Если "DocBook V4.2" не находится, значит вы не установили файлы DocBook DTD туда, где их может найти Jade, или не настроили корректно файлы каталогов. В этом случае воспользуйтесь указаниями, данными выше. При поиске таблиц стилей DocBook просматриваются несколько стандартных расположений, но если вы поместили их в другое место, вам, возможно, придётся задать это расположение в переменной окружения DOCBOOKSTYLE и затем перезапустить configure.
| Пред. | Начало | След. |
| DocBook | Уровень выше | Сборка документации |