Boost C++ 库

文档信息块有几种不同类型的属性。它们都是可选的。

Quickbook 特定的元数据

[quickbook 1.7]

quickbook 属性声明了文档编写所用的 quickbook 版本。如果缺省，则假定为 1.1 版本。建议您使用 [quickbook 1.7]，这是此处描述的版本。

	注意
	quickbook 版本也对生成的标记进行了一些更改。最值得注意的是，在较新版本中，为标题和章节自动生成的 id 是不同的。为了最大限度地减少中断，您可以使用 compatibility-mode 属性来生成类似于旧版本的标记 [article Article that was original written in quickbook 1.3 [quickbook 1.7] [compatibility-mode 1.3] ] 此功能不应用于新文档，仅用于将旧文档移植到新版本。

quickbook 和 compatibility-mode 标签都可以在文件开头、文档信息块之前以及没有文档信息块的文件中使用。

[source-mode teletype]

source-mode 属性设置初始 源模式。如果省略，将使用默认值 c++。

Boostbook/Docbook 根元素属性

[id foo]

id 指定文档元素的 id。如果未指定，则 id 会根据标题自动生成。此 id 也用于生成嵌套的 id。

[lang en]

lang 指定文档语言。docbook 使用它来本地化文档。请注意，Boostbook 没有本地化支持，因此如果您使用它来生成参考文档，它将始终是英文的。

它应该是从 ISO 639 中提取的语言代码（可能使用从 ISO 3166 中提取的国家代码进行扩展，例如 en-US）。

[dirname foo]

dirname 用于指定库在存储库中的目录名。这是 boostbook 扩展，因此仅对 library 文档块有效。它用于某些 boostbook 功能，但对于纯 quickbook 文档，它没有实际效果。

Docbook 元数据

version、copyright、authors、license、last-revision 和 bibliod 是可选信息。

Boostbook 元数据

purpose 和 category 是 boostbook 属性，仅对 library 文档有效。如果您将它们用于其他文档类型，quickbook 将会发出警告，但仍然会使用它们，生成无效的标记，这会被样式表忽略。

转义的 Docbook

从 quickbook 1.7 开始，转义的 boostbook 或 docbook 可以包含在 docinfo 块中

[article Some article
[quickbook 1.7]
'''<author>
    <firstname>John</firstname>
    <surname>Doe</surname>
    <email>john.doe@example.com</email>
</author>'''
]

转义的 docbook 始终放置在 docinfo 块的末尾，因此不应假定它会与从 quickbook 生成的标记交错。对于相同的信息，混合使用 quickbook 和 docbook 属性效果不佳。

Docinfo 块只能出现在 quickbook 文件的开头，因此要创建更复杂的文档，您需要使用多个 quickbook 文件并使用 include 标签 来嵌套它们。例如，假设您希望创建一个包含引言和章节的书籍，您首先需要为书籍创建一个文件

[book Simple example
[quickbook 1.7]
]

[include introduction.qbk]
[include chapter.qbk]

	注意
	像这样构造文档是在 quickbook 1.6 中引入的，因此需要 [quickbook 1.6] 或更高版本的 docinfo 字段。

引言的适当文档类型是 preface，因此 introduction.qbk 的内容应该类似于

[preface Introduction
[quickbook 1.7]
]

Write the introduction to the book here....

以及 chapter.qbk

[chapter A chapter
[quickbook 1.7]
]

Chapter contents....