Boost C++ Libraries Home Libraries People FAQ More


Documenting libraries 庫的文檔化

Defining a BoostBook library 定義一個 BoostBook 庫
From HTML to BoostBook 從 HTML 到 BoostBook
Sectioning in BoostBook 在 BoostBook 中的章節

BoostBook is an extension to DocBook, an XML format for representing documentation. BoostBook inherits much of its functionality and many elements from DocBook that are not redocumented here. When writing BoostBook documentation, please refer also to DocBook: The Definitive Guide.
BoostBook 是 DocBook 的一種擴展,它是描述文檔的一種 XML 格式。BoostBook 從 DocBook 繼承了許多功能和元素,在此不再重複。在編寫 BoostBook 文檔時,請一併參考 DocBook: The Definitive Guide

Defining a BoostBook library 定義一個 BoostBook 庫

BoostBook library documentation is contained entirely within a <library> XML element. To create a skeletal library, we need to create a new XML document (call it any.xml) that contains basic information about the library. The following BoostBook XML example describes basic information about the Boost.Any library:
BoostBook 的庫文檔被包含在一個 <library> XML 元素中。要創建一個框架庫,我們需要創建一個新的 XML 文檔(稱之為 any.xml)來包含該庫的基本信息。以下 BoostBook XML 示例 描述了關於 Boost.Any 庫的基本信息:

Example 26.1. A Skeletal BoostBook Library
示例 26.1. 一個 BoostBook 框架庫

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
<library name="Any" dirname="any" xmlns:xi=""
id="any" last-revision="$Date: 2008-07-12 15:30:45 -0400 (Sat, 12 Jul 2008) $">
Safe, generic container for single values of different value types
<librarycategory name="category:data-structures"/>

The first three lines identify this document as a BoostBook XML document. The DOCTYPE line states that the document conforms to the BoostBook DTD, and that the top-level element is a BoostBook <library>.
頭三行表示這個文檔是一個 BoostBook XML 文檔。DOCTYPE 行表示該文檔符合 BoostBook DTD,並且頂層元素為 BoostBook <library>。

The <library> element actually describes the aspects of BoostBook library documentation. The attributes for the <library> element are:
<library> 元素實際描述 BoostBook 庫文檔的外表。<library> 元素的屬性有:

Attributes for the <library> element
<library> 元素的屬性

The full name of the library, e.g., "Any"
庫的全名,如 "Any"
The name of the directory, relative to boost/libs, in which the library resides. This name may be a relative path, such as math/octonion, using "/" for the directory separator.
庫所在的目錄名,相對於 boost/libs。該名可以是一個相對路徑名,如 math/octonion,以 "/" 作為目錄分隔符。
A short, unique name for the library. For libraries with simple directory names (e.g., ones that do not contain a "/"), this should be the same as the dirname. This id will be used to identify libraries and, for HTML output, will be used as the base name for the HTML file in which the library's documentation resides, so it should use only lowercase alphanumeric characters and underscores.
庫的一個短且唯一的名字。對於帶有簡單目錄名的庫(即不含 "/"),該名字與 dirname 相同。這個 id 用於標識該庫,而且對於 HTML 輸出,它被用作庫文檔所處 HTML 文件的基名,所以它應該只使用小寫字母和下劃線。
Always set to $Date: 2008-07-12 15:30:45 -0400 (Sat, 12 Jul 2008) $, which is expanded by CVS to include the date and time that the file was last modified.
總是被設置為 $Date: 2008-07-12 15:30:45 -0400 (Sat, 12 Jul 2008) $,它會被 CVS 擴展為該文件最後修改的日期和時間。

Inside the <library> element we have the <libraryinfo> element, which gives information about the library itself. It contains the author's name (there may be more than one <author> element), followed by the purpose of the library and the list of categorizations. The <librarypurpose> element should always contain a very short (single sentence) description of the library's purpose, and should not terminate with a period.
在 <library> 元素內部,我們有 <libraryinfo> 元素,它給出關於庫本身的信息。它包含作者的姓名(可能有一個以上的 <author> 元素),接著是庫的用途和分類列表。 <librarypurpose> 元素應包含一個關於庫的用途的非常短的(單個句子)說明,且不應以句號結束。

The list of categories is specified by a set of <librarycategory> elements. Each <librarycategory> element has a name element that identifies one of the categories. The actual list of categories is in the file doc/src/boost.xml.
分類列表由一組 <librarycategory> 元素指定。每個 <librarycategory> 元素有一個標識一種類別的 name 元素。現行的分類列表在文件 doc/src/boost.xml 中。

At this point, we can apply the BoostBook XSL stylesheets to any.xml (to DocBook) followed by a DocBook XSL stylesheet to generate HTML output, as described in the section called 「Getting Started」.
到此為止,我們可以將 BoostBook XSL stylesheets 應用於 any.xml (至 DocBook)後跟 DocBook XSL stylesheet 以生成 HTML 輸出,正如 「入門」一節 中所描述的。

From HTML to BoostBook 從 HTML 到 BoostBook

Most library authors are comfortable with writing HTML documentation. Writing DocBook documentation (and, by extension, BoostBook documentation) is quite similar to writing HTML, except that BoostBook uses different element names from HTML (see Table 26.2, 「Converting HTML elements to BoostBook」) and BoostBook XML is a much more rigid format than HTML.
多數的庫作者都樂於編寫 HTML 文檔。編寫 DocBook 文檔(以及作為其擴展的 BoostBook 文檔)與編寫 HTML 非常相似,除了 BoostBook 使用了與 HTML 不同的元素名(請見 表 26.2, 「將 HTML 元素轉換至 BoostBook」),以及 BoostBook XML 具有比 HTML 更為嚴格的格式。

One of the easiest ways to convert HTML documentation into BoostBook documentation is to use HTML Tidy to transform your HTML into valid XHTML, which will make sure that all elements are properly closed, then apply the transformations in Table 26.2, 「Converting HTML elements to BoostBook」 to the body of the XHTML document. The following command uses HTML Tidy to transform HTML into valid XHTML:
將 HTML 文檔轉換為 BoostBook 文檔的一個最容易的方法是使用 HTML Tidy 來將你的 HTML 轉換為有效的 XHTML,以確保所有元素被正確關閉,然後將 表 26.2, 「將 HTML 元素轉換至 BoostBook」 中的轉換應用於 XHTML 文檔的 body。以下命令使用 HTML Tidy 來將 HTML 轉換為 XHTML:

  tidy -asxhtml input.html > output.xhtml

When converting documentation from HTML to BoostBook, note that some redundant information that has to be manually maintained in HTML is automatically generated in BoostBook: for instance, the library categorizations, purpose, and author list described in the section called 「Defining a BoostBook library」 are used both in the documentation for the library and to build alphabetical and categorized lists of known libraries; similarly, tables of contents are built automatically from the titles of sections in the BoostBook document.
在將文檔從 HTML 轉換為 BoostBook 時,注意有些在 HTML 中必須手工維護的冗余信息在 BoostBook 中是自動生成的:例如,在 「定義一個 BoostBook 庫」一節 中所描述的庫類別、用途和作者,這些信息即用在庫的文檔中,也用於構建已知庫的字母序列表和分類列表;同樣,目錄也是由 BoostBook 文檔中各章節的題目自動構建。

Table 26.2. Converting HTML elements to BoostBook
表 26.2. 將 HTML 元素轉換至 BoostBook

HTML BoostBook

<h1>, <h2>, etc.

<section>, <title>; See the section called 「Sectioning in BoostBook」

<section>, <title>; 參見 「BoostBook 中的章節」一節

<i>, <em>



<emphasis role="bold">












<para>, <simpara>


<xref>, <link>, <ulink>;, See the section called 「Linking in BoostBook」

<xref>, <link>, <ulink>;, 參見 「BoostBook 中的鏈接」一節

<table>, <tr>, <th>, <td>

<table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good tutorial here

<table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook 的表格和 DocBook 的表格一樣,這裡有一個好的 教程

Sectioning in BoostBook 在 BoostBook 中的章節

"Sectioning" refers to organization of a document into separate sections, each with a title, some text, and possibly subsections. Each section is described in BoostBook via a <section> element. An introduction section may look like this:
"分節" 是指將一個文檔組織成各個獨立的章節,每個章節有一個題目、一些文本,還可能有子章節。每一個章節在 BoostBook 中以一個 <section> 元素表示。例如,一個"簡介"章節可能如下:

<section id="any.intro">

<para>Introduction to a library...</para>

<title>A Subsection</title>
<para>Subsection information...</para>

The <section> element contains all information that should logically be grouped within that section. The title of the section is placed within the <title> element, and any paragraphs, programs, lists, tables, or subsections can occur within the section. The id attribute of the <section> element gives a unique ID to each section, so that it may later be identified for linking. It is suggested that all IDs start with the short name of a library followed by a period, so that IDs do not conflict between libraries.
<section> 元素包含了邏輯上組成某個章節的所有信息。章節的題目放在 <title> 元素中,章節的內部可以有段落、程序、列表、表格或子章節。<section> 元素的 id 屬性為每個章節給定一個唯一的 ID,這樣以後可以作為鏈接的標識。建議所有的 IDs 都以庫的短名加一個句號作為起始,這樣不同庫之間的 IDs 就不會衝突。