Boost C++ Libraries Home Libraries People FAQ More


Getting Started 入門

Automatic setup for Unix-like systems 類Unix系統上的自動設置
Manual setup for all systems 所有系統上的手動設置
Running BoostBook 運行 BoostBook
Troubleshooting 疑難解答

To use the Boost documentation tools, you will need several tools:
要使用 Boost 文檔工具,你需要以下幾個工具:

Automatic setup for Unix-like systems 類Unix系統上的自動設置

BoostBook provides a nearly-automatic setup script. Once you have downloaded and installed xsltproc, doxygen, and (optionally) java, the setup script can download the required DocBook stylesheets, DocBook DTD, and (when Java is enabled) Apache FOP for PDF output. It will then configure Boost.Build version 2 to build BoostBook documentation. To perform the installation, execute the script tools/boostbook/ from a directory where you would like the resulting XSL, DTD, and Apache FOP installations to occur.
BoostBook 提供了幾乎是自動化的設置腳本。在你下載並安裝完成 xsltproc, doxygen, 還有(可選的) java 後,設置腳本就可以下載所需的 DocBook stylesheets, DocBook DTD, 和(如果 Java 是可用的)用於 PDF 輸出的 Apache FOP。然後它將配置 Boost.Build V2 以構建 BoostBook 文檔。要進行這個安裝,請從一個你想要存放最終的 XSL, DTD 和 Apache FOP 安裝的目錄下執行腳本 tools/boostbook/

Manual setup for all systems 所有系統上的手動設置

This section describes how to manually configure Boost Boost version 2 (BBv@) for BoostBook. If you can use the automatic setup script, you should. All configuration will happen in the BBv2 user configuration file, user-config.jam. If you do not have a copy of this file in your home directory, you should copy the one that resides in tools/build/v2 to your home directory. Alternatively, you can edit tools/build/v2/user-config.jam directly or a site-wide site-config.jam file.
本節描述了如何為 BoostBook 手工配置 Boost Boost version 2 (BBv@)。如果你可以使用自動腳本,你就應該用它。所有配置都出現在 BBv2 的用戶配置文件 user-config.jam 中。如果在你的主目錄中沒有這個文件的拷貝,你可以從 tools/build/v2 目錄中複製一份到你的主目錄。或者,你也可以直接編輯 tools/build/v2/user-config.jam 或是一個 site-wide site-config.jam 文件。

Configuring xsltproc 配置 xsltproc

To configure xsltproc manually, you will need to add a directive to user-config.jam telling it where to find xsltproc. If the program is in your path, just add the following line to user-config.jam:
要手工配置 xsltproc,你需要增加一個指示符到 user-config.jam 中,告訴它在哪裡可以找到 xsltproc。如果該程序在你的執行目錄中,則只需要增加以下一行到 user-config.jam 中:

using xsltproc ;

If xsltproc is somewhere else, use this directive, where XSLTPROC is the full pathname to xsltproc (including xsltproc):
如果 xsltproc 在其它的地方,請使用以下指示符,其中 XSLTPROCxsltproc (包括 xsltproc) 的全路徑名:

using xsltproc : XSLTPROC ;

Configuring local DocBook XSL and DTD distributions 配置本地的 DocBook XSL 和 DTD 分發包

This section describes how to configure Boost.Build to use local copies of the DocBook DTD and XSL stylesheets to improve processing time. You will first need to download two packages:
這一節描述如何配置 Boost.Build 來使用本地的 DocBook DTD 和 XSL stylesheets 來提高處理速度。首先你要下載兩個包:

  • Norman Walsh's DocBook XSL stylesheets, available at the DocBook sourceforge site. Extract the DocBook XSL stylesheets to a directory on your hard disk (which we'll refer to as the DOCBOOK_XSL_DIR).
    Norman Walsh 的 DocBook XSL stylesheets,在 DocBook sourceforge 站點。將該 DocBook XSL stylesheets 解壓到你硬盤上的某個目錄(我們將稱之為 DOCBOOK_XSL_DIR)。

  • The DocBook DTD, available as a ZIP archive at the OASIS DocBook site. The package is called "DocBook XML 4.2". Extract the DocBook DTD to a directory on your hard disk (which we'll refer to as the DOCBOOK_DTD_DIR). You will want to extract this archive in a subdirectory!
    DocBook DTD, 它是一個 ZIP 存檔,在 OASIS DocBook 站點。該包稱為 "DocBook XML 4.2"。將該 DocBook DTD 解壓到你硬盤上的某個目錄(我們將稱之為 DOCBOOK_DTD_DIR)。你應該將該存檔解壓到一個子目錄下!

Add the following directive telling BBv2 where to find the DocBook DTD and XSL stylesheets:
增加以下指示符,告訴 BBv2 在哪裡可以找到 DocBook DTD 和 XSL stylesheets:

#  BoostBook configuration
using boostbook

Whenever you change this directive, you will need to remove the bin.v2 directory that BBv2 generates. This is due to longstanding bug we are trying to fix.
如果你修改了這個指示符,你就需要刪除由 BBv2 生成的 bin.v2 目錄。這是一個已經存在很長時間的 bug,我們正在努力修復它。

At this point, you should be able to build HTML documentation for libraries that do not require Doxygen. To test this, change into the directory $BOOST_ROOT/libs/function/doc and run the command bjam --v2: it should produce HTML documentation for the Boost.Function library in the html subdirectory.
到此為止,你應該可以為各個不需要 Doxygen 的庫構建 HTML 文檔了。要測試一下它,請轉至 $BOOST_ROOT/libs/function/doc 目錄,運行命令 bjam --v2: 它會為 Boost.Function 庫生成 HTML 文檔並保存在 html 子目錄下。

Configuring Doxygen for Documentation Extraction 為文檔提取配置 Doxygen

Doxygen is required to build the documentation for several Boost libraries. You will need a recent version of Doxygen (most of the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the following directive to user-config.jam:
有幾個 Boost 庫的文檔要用 Doxygen 構建。你需要較新版本的 Doxygen (多數 1.3.x 和 1.4.x 版本都可以)。增加以下指示符到 BBv2 的 user-config.jam:

using doxygen : DOXYGEN ;

DOXYGEN should be replaced with the name of the doxygen executable (with full path name). If the right doxygen executable can be found via the path, this parameter can be omitted, e.g.
DOXYGEN 應被替換為 doxygen 可執行文件的名字(帶全路徑名)。如果可以在執行路徑中找到正確的 doxygen 可執行文件,該參數可以忽略,如:

using doxygen ;
[Important] Important 重要

The relative order of declarations in user-config.jam / site-config.jam files is significant. In particular, the using doxygen line should come after the using boostbook declaration.

user-config.jam / site-config.jam 文件中的聲明的相對順序是很重要的。特別是,using doxygen 行應在 using boostbook 聲明之後。

Configuring Apache FOP 配置 Apache FOP

In order to generate PDF and PostScript output using Apache FOP, you will need a Java interpreter and Apache FOP (version 0.20.5 is best). Unpack Apache FOP to some directory. The top level directory of the FOP tool should contain a main script called on Unix and fop.bat on Windows. You need to specify the location of that script and Java location to Boost.Build. Add the following to your user-config.jam or site-config.jam:
為了使用 Apache FOP 生成 PDF 和 PostScript 輸出,你需要一個 Java 解釋器Apache FOP (最好是版本 0.20.5)。將 Apache FOP 解包到某個目錄。FOP 工具的頂層目錄應包含一個主腳本,在 Unix 中名為,在 Windows 中則名為 fop.bat。你需要對 Boost.Build 指明該腳本的位置和 Java 的位置。增加以下行到你的 user-config.jamsite-config.jam:

using fop : FOP_COMMAND 

replacing FOP_COMMAND with the full path to the FOP main script, and replacing JAVA_HOME with the directory where Java is installed. If the JAVA_HOME environment variable is already set, you don't need to specify it above.
FOP_COMMAND 替換為 FOP 主腳本的全路徑,再將 JAVA_HOME 替換為安裝 Java 的目錄。如果已經設置了 JAVA_HOME 環境變量,你就不需要再指定它了。

Proper generation of images in PDFs depends on the Jimi Image Library. To get FOP to use Jimi, extract the file from the Jimi SDK and rename it—if on Windows, to jimi-1.0.jar, or if on *nix, to JimiProClasses.jar—and place it in the lib/ subdirectory of your FOP installation.
PDF 中的圖像的正確生成要依靠 Jimi 圖像庫。要讓 FOP 使用 Jimi,請從 Jimi SDK 中解壓 文件並改名—對於 Windows 改為 jimi-1.0.jar,對於 *nix 則改為 JimiProClasses.jar—並將它放在你的 FOP 安裝下的 lib/ 子目錄。

To test PDF generation, switch to the directory $BOOST_ROOT/libs/function/doc and execute the command bjam --v2 pdf. In the absence of any errors, Apache FOP will be executed to transform the XSL:FO output of DocBook into a PDF file.
要測試 PDF 的生成,請轉至 $BOOST_ROOT/libs/function/doc 目錄並執行命令 bjam --v2 pdf。如果一切正常,Apache FOP 將會執行並將 DocBook 的 XSL:FO 輸出轉換為 PDF 文件。

Running BoostBook 運行 BoostBook

Once BoostBook has been configured, we can build some documentation. First, change to the directory $BOOST_ROOT/doc and remove (or make writable) the .html files in $BOOST_ROOT/doc/html. Then, run bjam --v2 to build HTML documentation. You should see several warnings like these while DocBook documentation is being built from BoostBook documentation:
一旦完成 BoostBook 的配置,我們就可以來構建一些文檔了。首先,轉至 $BOOST_ROOT/doc 目錄並刪除(或使之可寫)在 $BOOST_ROOT/doc/html 中的 .html 文件。然後,運行 bjam --v2 來構建 HTML 文檔。在從 BoostBook 文檔構建 DocBook 文檔過程中,你會看到如下一些警告:

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

These warnings are emitted when the Boost documentation tools cannot find documentation for functions, methods, or classes that are referenced in the source, and are not harmful in any way. Once Boost.Jam has completed its execution, HTML documentation for Boost will be available in $BOOST_ROOT/doc/html. You can also create HTML documentation in a single (large!) HTML file with the command line bjam --v2 onehtml, or Unix man pages with the command line bjam --v2 man. The complete list of output formats is listed in Table 26.1, 「BoostBook Output Formats」. Several output formats can be passed to a single invocation of bjam, e.g., bjam --v2 html man docbook would generate HTML (multiple files), man pages, and DocBook documentation.
這些警告是在 Boost 文檔工具找不到源文件中某些函數、方法或類的文檔時產生的,它們沒有什麼危害。當 Boost.Jam 完成執行後,Boost 的 HTML 文檔將被放在 $BOOST_ROOT/doc/html 目錄中。你也可以用命令行 bjam --v2 onehtml 來生成單個(巨大的!) HTML 文件,或者用命令行 bjam --v2 man 來生成 Unix man 頁。完成的輸出格式列表請見 表 26.1, 「BoostBook 輸出格式」。可以在對 bjam 的一次調用中生成多種輸出格式,如 bjam --v2 html man docbook 將同時生成 HTML (多文件), man 頁和 DocBook 文檔。

Table 26.1. BoostBook Output Formats
表 26.1. BoostBook 輸出格式

Format 格式 Description 說明

HTML output (multiple files). This is the default

HTML 輸出(多文件)。這是缺省值。


HTML output in a single HTML file.

單個 HTML 文件的 HTML 輸出。


Unix man pages.

Unix man 頁。


PDF. Requires Apache FOP.

PDF. 需要 Apache FOP.


Postscript. Requires Apache FOP.

Postscript. 需要 Apache FOP.

docbook DocBook.
fo XSL Formatting Objects

Troubleshooting 疑難解答

The Boost documentation tools are still in their early phase of development, and some things don't work as seamlessly as we would like them to, yet. In particular, error messages can be somewhat uninformative at times. If you find yourself in the situation when you have double checked everything, and yet things still don't work as expected, consider helping the tools by deleting bin.v2 build directory.
Boost 文檔工具仍然只是處於開發的早期階段,有些事情還不是像我們希望的那樣無縫工作。特別是,有時的錯誤信息毫無意義。如果你發現這種情況,並經過反覆檢查後依然無法正常使用,可以考慮通過刪除 bin.v2 構建目錄來幫這些工具一把。