第 3 章。文档化库

定义 BoostBook 库
从 HTML 到 BoostBook
BoostBook 中的章节

BoostBook 是 DocBook 的扩展，DocBook 是一种用于表示文档的 XML 格式。BoostBook 继承了 DocBook 的大部分功能和许多元素，在此不再重复说明。在编写 BoostBook 文档时，请同时参考 DocBook: 权威指南。

定义 BoostBook 库

BoostBook 库文档完全包含在 <library> XML 元素中。要创建骨架库，我们需要创建一个新的 XML 文档（命名为 any.xml），其中包含有关库的基本信息。以下 BoostBook XML 示例描述了有关 Boost.Any 库的基本信息

示例 3.1. 骨架 BoostBook 库

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  "https://boost.ac.cn/tools/boostbook/dtd/boostbook.dtd">
<library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude"
  id="any" last-revision="$Date$">
  <libraryinfo>
    <author>
      <firstname>Kevlin</firstname>
      <surname>Henney</surname>
    </author>
    <librarypurpose>
      Safe, generic container for single values of different value types
    </librarypurpose> 
    <librarycategory name="category:data-structures"/>
  </libraryinfo>
</library>

前三行将此文档标识为 BoostBook XML 文档。DOCTYPE 行声明该文档符合 BoostBook DTD，并且顶层元素是 BoostBook <library>。

<library> 元素实际上描述了 BoostBook 库文档的各个方面。<library> 元素的属性是

<library> 元素的属性

name: 库的完整名称，例如，“Any”
dirname: 目录的名称，相对于 boost/libs，库驻留在此目录中。此名称可以是相对路径，例如 math/octonion，使用“/”作为目录分隔符。
id: 库的简短、唯一名称。对于目录名称简单的库（例如，不包含“/”的库），这应与 dirname 相同。此 id 将用于标识库，并且对于 HTML 输出，将用作库文档所在的 HTML 文件的基本名称，因此它应仅使用小写字母数字字符和下划线。
last-revision: 始终设置为 $Date$ ，CVS 会将其展开以包含文件上次修改的日期和时间。

在 <library> 元素内部，我们有 <libraryinfo> 元素，它提供有关库本身的信息。它包含作者的姓名（可能有一个以上的 <author> 元素），后跟库的用途和分类列表。<librarypurpose> 元素应始终包含库用途的非常简短的（单句）描述，并且不应以句点结尾。

类别列表由一组 <librarycategory> 元素指定。每个 <librarycategory> 元素都有一个 name 元素，用于标识其中一个类别。实际的类别列表在文件 doc/src/boost.xml 中。

此时，我们可以将 BoostBook XSL 样式表应用于 any.xml（到 DocBook），然后将 DocBook XSL 样式表应用于生成 HTML 输出，如第 2 章，入门中所述。

Boost C++ 库

第 3 章。文档化库

定义 BoostBook 库