Boost C++ Libraries Home Libraries People FAQ More


Chapter 27. The BoostBook Documentation Format

Douglas Gregor

Permission to copy, use, sell and distribute this software is granted provided this copyright notice appears in all copies. Permission to modify the code and to distribute modified code is granted provided this copyright notice appears in all copies, and a notice that the code was modified is included with the copyright notice.

This software is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

Table of Contents 目錄

Introduction 簡介
Getting Started 入門
Automatic setup for Unix-like systems 用於類Unix系統的自動設置
Manual setup for all systems 用於所有系統的手動設置
Running BoostBook 運行 BoostBook
Troubleshooting 疑難解答
Documenting libraries 將庫文檔化
Defining a BoostBook library 定義一個 BoostBook 庫
From HTML to BoostBook 從 HTML 到 BoostBook
Sectioning in BoostBook 在 BoostBook 中的章節
Bringing Together a BoostBook Document 集合成一個 BoostBook 文檔
Linking in BoostBook 在 BoostBook 中的鏈接
Reference 參考手冊

Introduction 簡介

The BoostBook documentation format is an extension of DocBook, an SGML- or XML-based format for describing documentation. BoostBook augments DocBook with semantic markup that aids in the documentation of C++ libraries, specifically the Boost C++ libraries, by providing the ability to express and refer to C++ constructs such as namespaces, classes, overloaded functions, templates, and specializations.
BoostBook 文檔格式是 DocBook 的一種擴展,後者是一種用於描述性文檔的基於 SGML 或 XML 的格式。BoostBook 比 DocBook 增加了語義標記,有助於編寫 C++ 庫的文檔,尤其是 Boost C++ 庫,它提供了表示和引用象名字空間、類、函數重載、模板和特化等 C++ 結構的能力。

BoostBook offers additional features more specific to its use for documenting the Boost C++ libraries. These features are intended to eliminate or reduce the need for duplication of information and to aid in documenting portions of Boost that might otherwise not be documented. Examples of Boost-centric features include:
BoostBook 提供了額外的特性,更加專注於 Boost C++ 庫 的文檔編寫。這些特性的目的是消除或減少重複的信息,並有助於將未文檔化的 Boost 部分進行文檔化。Boost-專用的特性包括有:

  • Testsuites: Testsuites in Boost are created by writing an appropriate Jamfile and including that Jamfile in status/Jamfile. If the testsuites are documented (as in the MultiArray library), the documentation is maintained separately from the testcase Jamfile, leading to duplication of information and the possibility of having the documentation out of sync with the Jamfile. BoostBook contains elements that describe a testsuite for both purposes: the BoostBook stylesheets can generate documentation for the testcases and also generate an appropriate Jamfile to integrate the testcases with the regression testing system.
    測試套件:Boost 中的測試套件是通過編寫一個合適的 Jamfile 並將該 Jamfile 包含在 status/Jamfile 中來創建的。如果測試套件已經文檔化(像在 MultiArray 庫中),則這些文檔的維護是獨立於測試案例 Jamfile 的,這導致了信息的重複,還可能使得文檔與 Jamfile 不同步。BoostBook 包含了描述一個測試套的各種元素,有兩種目的:BoostBook stylesheets 可以為測試案例生成文檔,也可以生成一個適合的 Jamfile 來將測試案例與回歸測試系統相集成。

  • Example programs: Example programs in documentation need to be duplicated in testcases to ensure that the examples compile and execute correctly. Keeping the two copies in sync is a tedious and error-prone task. For instance, the following code snippet persisted for six months:

    std::cout << f(5, 3) >> std::endl;

    The BoostBook format allows testcases to be generated by weaving together program fragments from example programs in the documentation. This capability is integrated with testsuite generation so that example programs are normal tests in BoostBook.
    BoostBook 格式可以通過組合多個程序片斷,從文檔中的示例程序生成測試案例。這一能力被集成到測試套件的生成當中,這樣在 BoostBook 中的示例程序就可以進行正常的測試。