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

J.2. Инструментарий

J.2.1. Установка в Fedora, RHEL и производных системах
J.2.2. Установка во FreeBSD
J.2.3. Пакеты Debian
J.2.4. OS X
J.2.5. Установка из исходного кода вручную
J.2.6. Проверка условий configure

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

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-sgml

  • textproc/docbook-xml

  • textproc/docbook-xsl

  • textproc/dsssl-docbook-modular

  • textproc/libxslt

  • textproc/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

  1. Установка 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 должно решить эту проблему.

  2. Кроме того, вы должны установить файлы dsssl.dtd, fot.dtd, style-sheet.dtd и catalog из каталога dsssl в определённое место, возможно, в /usr/local/share/sgml/dsssl. Вероятно, проще всего для этого будет скопировать весь каталог: 

    cp -R dsssl /usr/local/share/sgml

  3. Наконец, создайте файл /usr/local/share/sgml/catalog и добавьте в него эту строку: 

    CATALOG "dsssl/catalog"

    (Это ссылка по относительному пути на файл, установленный на Шаг 2. Обязательно скорректируйте этот путь, если ваша инсталляция имеет другую структуру.)

J.2.5.2. Установка DocBook DTD

  1. Получите пакет DocBook V4.2.

  2. Создайте каталог /usr/local/share/sgml/docbook-4.2 и перейдите в него. (Расположение может быть и другим, но данный путь соответствует структуре каталогов, которой мы следуем здесь.) 

    $ mkdir /usr/local/share/sgml/docbook-4.2
$ cd /usr/local/share/sgml/docbook-4.2

  3. Распакуйте архив: 

    $ unzip -a ...../docbook-4.2.zip

    (Файлы архива будут распакованы в текущий каталог.)

  4. Отредактируйте файл /usr/local/share/sgml/catalog (или тот, что был указан при инсталляции jade) и добавьте в него такую строку: 

    CATALOG "docbook-4.2/docbook.cat"

  5. Загрузите архив сущностей символов ISO 8879, распакуйте его и поместите файлы в тот же каталог, в который вы поместили файлы DocBook: 

    $ cd /usr/local/share/sgml/docbook-4.2
$ unzip ...../ISOEnts.zip

  6. Запустите в каталоге с файлами 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.

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

Чтобы сделать работу с сайтом удобнее, мы используем cookie и аналитический сервис «Яндекс.Метрика». Продолжая пользоваться сайтом, вы соглашаетесь с их использованием.