J.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, но в официальных выпусках Postgres Pro для этого используются стили DSSSL.
На данный момент требуется версия как минимум 1.74.0.
- OpenJade
Это базовый пакет для обработки SGML. В него входит средство разбора SGML, процессор DSSSL (то есть программа, преобразующая SGML в другие форматы, применяя стили DSSSL), а также ряд связанных инструментов. Поддержкой Jade теперь занимается не Джеймс Кларк, а группа OpenJade.
- Libxml2 для
xmllint Эта библиотека и включённая в неё утилита
xmllintприменяются для обработки XML. У многих разработчиков библиотека Libxml2 уже установлена, потому что она также используются при сборке кода Postgres Pro. Заметьте, однако, чтоxmllintможет потребоваться установить из отдельного пакета.- Libxslt для
xsltproc Это средство преобразования с применением стилей XSLT (как
jade— средство преобразования с применением стилей DSSSL).- JadeTeX
Если хотите, вы также можете установить JadeTeX, чтобы использовать TeX как модуль форматирования для Jade. JadeTeX может создавать файлы PostScript и PDF (последние с закладками).
Однако вывод JadeTeX уступает тому, что можно получить через RTF. В частности, проблемы возникают с таблицами, а также с горизонтальными и вертикальными отступами. Кроме того, при таком выводе нет возможности вручную отполировать результаты.
Ниже мы опишем различные варианты установки программного обеспечения, необходимого для обработки документации. Эти программы могут распространяться и в других пакетах. Пожалуйста, сообщите о состоянии конкретного пакета в список рассылки, посвящённый документации, и мы добавим эту информацию сюда.
J.2.1. Установка в Fedora, RHEL и производных системах
Чтобы установить требуемые пакеты, выполните:
yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade
J.2.2. Установка во FreeBSD
Проект документации FreeBSD сам активно использует DocBook, поэтому неудивительно, что для FreeBSD есть полный набор «портов» инструментария для сборки документации. Чтобы собирать документацию во FreeBSD, необходимо установить нижеперечисленные порты.
textproc/docbook-sgmltextproc/docbook-xmltextproc/docbook-xsltextproc/dsssl-docbook-modulartextproc/libxslttextproc/openjade
Также могут представлять интерес некоторые вещи из /usr/ports/print (tex, jadetex).
Дополнительные сведения об инструментарии документации FreeBSD можно найти в инструкциях проекта документации FreeBSD.
J.2.3. Пакеты Debian
Для Debian GNU/Linux имеется полный набор пакетов инструментария сборки документации. Чтобы установить их, просто выполните:
apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc
J.2.4. OS X
Если вы используете систему MacPorts, вы можете получить необходимое программное обеспечение так:
sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp
J.2.5. Установка из исходного кода вручную
Процесс установки инструментария DocBook довольно сложен, поэтому, если для вашей системы есть готовые пакеты, используйте их. Мы опишем здесь только стандартную процедуру с обычными путями инсталляции и без «экстраординарных» функций. За подробностями вы можете обратиться к документации соответствующего пакета или вводному материалу по SGML.
J.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. Обязательно скорректируйте этот путь, если ваша инсталляция имеет другую структуру.)
J.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.)
J.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"Так как таблицы стилей меняются довольно часто и иногда имеет смысл использовать альтернативные версии, документация Postgres Pro не использует эту запись каталога. Как выбрать таблицы стилей для неё, описано в Подразделе J.2.6.
J.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 с исходным материалом документации Postgres Pro, вам необходимо увеличить размер внутренних структур данных TeX. Подробнее об этом рассказывается в инструкциях по установке JadeTeX.
Выполнив необходимые условия, вы можете установить JadeTeX так:
$gunzip jadetex-xxx.tar.gz$tar xf jadetex-xxx.tar$cd jadetex$make install$mktexlsr
Последние две команды нужно выполнять от имени root.
J.2.6. Проверка условий configure
Прежде чем вы сможете собрать документацию, вы должны запустить скрипт configure так же, как это нужно сделать для сборки программной части Postgres Pro. Обратите внимание на сообщения, выводимые ближе к концу. Вы должны увидеть примерно следующее:
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.