Getting Started . Boost , The Boost C++ Libraries BoostBook Documentation Subset , Chapter 44. The BoostBook Documentation Format

Getting Started

Automatic setup for Unix-like systems
Manual setup for all systems
Running BoostBook
Troubleshooting

Для использования инструментов документации Boost вам понадобится несколько инструментов:

xsltproc:
- Windows сCygwin: Выберите пакеты libxml2 и libxslt.
- Windows без Cygwin: Скачатьбинарные пакетыот Игоря Златковича. По крайней мере, вам понадобятся iconv, zlib, libxml2 и libxslt.
- Mac OS X с Fink: Получить<libxslt>пакет.
- Mac OS X без Финка:Скачать libxslt двоичные файлы
- Любые платформы:libxslt источник.
доксиген:
Доступно изhttp://www.doxygen.org

Automatic setup for Unix-like systems

BoostBook предоставляет почти автоматический скрипт настройки. После того, как вы загрузили и установилиxsltproc,doxygenи (необязательно)java, скрипт настройки может загрузить необходимые таблицы стилей DocBook, DocBook DTD и (когда включена Java) Apache FOP для вывода PDF. Затем он настроит Boost. Создайте версию 2 для создания документации BoostBook.

Сценарий требует:ш,завитокигунцип. Чтобы выполнить установку, выполните скриптинструментов /boostbook /setup_boostbook.shиз каталога, где вы хотели бы, чтобы в результате возникли установки XSL, DTD и Apache FOP.

Manual setup for all systems

Configuring xsltproc
Configuring local DocBook XSL and DTD distributions
Configuring Doxygen for Documentation Extraction
Configuring Apache FOP

В этом разделе описывается, как вручную настроить Boost Boost версии 2 (BBv@) для BoostBook. Если вы можете использовать скрипт автоматической настройки, вы должны. Вся конфигурация будет происходить в файле конфигурации пользователя BBv2<user-config.jam>. Если у вас нет копии этого файла в домашнем каталоге, вы должны скопировать тот, который находится в<tools/build/>. Кроме того, вы можете редактировать<tools/build/user-config.jam>напрямую или файл<site-config.jam>по всему сайту.

Configuring xsltproc

Чтобы настроитьxsltprocвручную, вам нужно будет добавить директиву к<user-config.jam>, сообщающую ему, где найтиxsltproc. Если программа находится на вашем пути, просто добавьте следующую строку<user-config.jam>:

using xsltproc ;

Еслиxsltprocнаходится где-то еще, используйте эту директиву, где<XSLTPROC>является полным именем пути кxsltproc(включаяxsltproc):

using xsltproc : XSLTPROC ;

Configuring local DocBook XSL and DTD distributions

В этом разделе описывается, как настроить Boost. Создайте локальные копии таблиц стилей DocBook DTD и XSL, чтобы улучшить время обработки. Сначала вам нужно будет загрузить два пакета:

таблицы стилей DocBook XSL Нормана Уолша, доступные на сайтеDocBook sourceforge. Извлеките таблицы стилей DocBook XSL в каталог на вашем жестком диске (который мы будем называть<DOCBOOK_XSL_DIR>).
DocBook DTD, доступный в виде ZIP-архива на сайтеOASIS DocBook. Он называется «DocBook XML 4.2». Извлеките DocBook DTD в каталог на вашем жестком диске (который мы будем называть<DOCBOOK_DTD_DIR>). Вы захотите извлечь этот архив в подкаталоге!

Добавьте следующую директиву, сообщающую BBv2, где найти таблицы стилей DocBook DTD и XSL:

#  BoostBook configuration
using boostbook 
  : DOCBOOK_XSL_DIR
  : DOCBOOK_DTD_DIR
  ;

Всякий раз, когда вы меняете эту директиву, вам нужно удалить каталог<bin.v2>, который генерирует BBv2. Это связано с давними ошибками, которые мы пытаемся исправить.

На этом этапе вы должны иметь возможность создавать HTML-документацию для библиотек, которые не требуют Doxygen. Чтобы проверить это, перейдите в каталог<$BOOST_ROOT/libs/function/doc>и запустите команду<bjam>: он должен создавать HTML-документацию для Boost. Функциональная библиотека в подкаталоге<html>.

Configuring Doxygen for Documentation Extraction

Доксиген необходим для создания документации для нескольких библиотек Boost. Вам понадобится недавняя версияDoxygen(большинство версий 1.3.x и 1.4.x будет достаточно). BBv2, добавляя следующую директиву к<user-config.jam>:

using doxygen : DOXYGEN ;

<DOXYGEN>следует заменить надоксигенисполняемый (с полным названием пути). Если правыйдоксигенисполняемый может быть найден через путь, этот параметр может быть опущен, например.

using doxygen ;

	Important
	Относительный порядок деклараций в<`user-config.jam`>/<`site-config.jam`>файлах значителен. В частности,<`using doxygen`>строка должна прийтипосле<`using boostbook`>декларации.

Configuring Apache FOP

Чтобы генерировать PDF и PostScript с помощью Apache FOP, вам понадобится. Переводчик JavaиApache FOP(версия 0.20.5 лучше всего). Распакуйте Apache FOP в какой-нибудь каталог. Каталог верхнего уровня инструмента FOP должен содержать основной скрипт под названием<fop.sh>на Unix и<fop.bat>на Windows. Вам нужно указать местоположение этого скрипта и местоположение Java для увеличения. Построй. Добавьте к<user-config.jam>или<site-config.jam>следующее:

using fop : FOP_COMMAND 
          : JAVA_HOME 
          ;

Замена<FOP_COMMAND>полным путем к основному скрипту FOP и замена<JAVA_HOME>каталогом, где установлена Java. Если переменная среды<JAVA_HOME>уже установлена, вам не нужно указывать ее выше.

Правильное генерирование изображений в PDF зависит отJimi Image Library. Чтобы получить FOP для использования Jimi, извлеките файл<JimiProClasses.zip>из Jimi SDK и переименуйте его & #8212; если в Windows, в<jimi-1.0.jar>, или если на *nix, в<JimiProClasses.jar>& #8212; и поместите его в<lib/>подкаталог вашей установки FOP.

Для тестирования генерации PDF перейдите в каталог<$BOOST_ROOT/libs/function/doc>и выполните командуbjam pdf. При отсутствии каких-либо ошибок Apache FOP будет выполняться для преобразования вывода XSL:FO DocBook в PDF-файл.

Running BoostBook

После настройки BoostBook мы можем создать некоторую документацию. Во-первых, измените каталог<$BOOST_ROOT/doc>и удалите<.html>файлов<$BOOST_ROOT/doc/html>. Затем запустите<bjam>для создания HTML-документации. Вы должны увидеть несколько подобных предупреждений, когда документация DocBook строится из документации BoostBook:

Cannot find function named 'checked_delete'
Cannot find function named 'checked_array_delete'
Cannot find function named 'next'

Эти предупреждения испускаются, когда инструменты документации Boost не могут найти документацию для функций, методов или классов, на которые ссылаются в источнике, и никоим образом не вредны. Когда-то повышали. Jam завершил свое исполнение, HTML-документация для Boost будет доступна в<$BOOST_ROOT/doc/html>. Вы также можете создать HTML-документацию в одном (большом!) формате. HTML-файл с командной строкой<bjam onehtml>, или страницы Unix man с командной строкой<bjam man>. Полный список выходных форматов приведен вTable 44.1, “BoostBook Output Formats”. Несколько выходных форматов могут быть переданы одному вызову<bjam>, например,<bjam html man docbook>будет генерировать HTML (множество файлов), человеческие страницы и документацию DocBook.

Table 44.1. BoostBook Output Formats

Format	Description
html	HTML выход (несколько файлов). В этом и состоит суть .
хетмл	HTML вывод в одном HTML-файле.
человек	Мужские страницы Unix.
pdf	PDF. ТребуетсяApache FOP .
ps	Постскриптум. ТребуетсяApache FOP .
книга	Докбук.
туман	XSL Форматирование объектов

Troubleshooting

Инструменты документации Boost все еще находятся на ранней стадии разработки, и некоторые вещи пока работают не так гладко, как хотелось бы. В частности, сообщения об ошибках иногда могут быть неинформативными. Если вы окажетесь в ситуации, когда вы дважды проверили все, но все еще не работает, как ожидалось, подумайте о том, чтобы помочь инструментам, удалив<bin.v2>каталог сборки.

Статья Getting Started раздела The Boost C++ Libraries BoostBook Documentation Subset Chapter 44. The BoostBook Documentation Format может быть полезна для разработчиков на c++ и boost.