Boost C++ 库

['italic], [*bold], [_underline], [^teletype], [-strikethrough]

将生成

斜体, 粗体, 下划线, 电传打字机，删除线

当然，就像所有非末端短语级元素一样，这也是可以嵌套的

[*['bold-italic]]

将生成

粗斜体

当你想要用户可以或必须替换的内容时，请使用以下语法

[~replacement]

这将生成

替换

["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein

将生成

“有时困扰我的问题：是我发疯了还是其他人发疯了？”--爱因斯坦

请注意正确的左右引号。而且，虽然你可简单地使用普通引号，如“引用”，但上面我们的引号将生成正确的 DocBook 引号（例如 <quote>引用</quote>）。

如同所有短语元素一样，引号也可以嵌套。示例

["Here's the rule for bargains: ["Do other men, for they would do you.] That's
the true business precept.]

将生成

“以下是谈判规则：‘以彼之道还施彼身。’ 那是真正的商业戒律。”

现在支持用于格式化文本的简单标记，这种标记在很多应用程序中很常见

/italic/, *bold*, _underline_, =teletype=

将生成

斜体, 粗体, 下划线, 电传打字机

与 QuickBook 的标准格式化方案不同，更简单替代方案的规则更加严格^[34]。

如前所述，简单的标记不能超过单个块。以下段落中“have”到“full”的文本将被呈现为粗体

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!*
One for the master, one for the dame,
And one for the little boy who lives down the lane.

小羊baa baa黑，你有没有羊毛？是的，是的，三袋装满！一袋给主人，一袋给太太，还有一袋给住在巷子里的那个小男孩。

但在下面的段落中，没有应用粗体

Baa baa black sheep, *have you any wool?
Yes sir, yes sir, three bags full!
One for the master, one for the dame,
And one for the little boy who lives down the lane.

小羊baa baa黑，*你有没有羊毛？是的，是的，三袋装满！一袋给主人，一袋给太太，还有一袋给住在巷子里的那个小男孩。

这会生成带有 role 属性的 Docbook 短语，该属性可用于对短语进行分类。这可用于标记不包括在其他地方用途的文本。Docbook role 将生成一个 html 类，该类可用于设置文本样式。当生成 PDF 时，可以自定义 XSL 样式表以特殊地处理某些角色。

boostbook css 样式表和 xsl 样式表支持可与 role 结合使用的一系列色彩。例如，如果你编写

[role red Text content]

如果使用 boostbook css（html 版）或 boostbook xsl 生成 pdf，则文本将会变为红色。

可用色彩的完整列表包括

在撰写 C++ 文档时，通常需要在段落中内联代码。我们为此提供了一种非常简单的标记。例如，

This text has inlined code `int main() { return 0; }` in it.

将生成

该文本中内联了代码 int main() { return 0; }。该代码将突出显示语法。

	请注意
	我们只需用单引号 "`"（而不是单引号 "'"）将代码括起来。还要注意，相较于 [^some code]，我们更推荐 `some code`。

只需以空格或制表符开头即可预先格式化代码（参见 代码）。但是，这种简单的语法无法用作列表中的短语元素（参见 有序列表 和 无序列表）、表格（参见 表格）等。而内联代码（见上文）可以。问题在于内联代码不允许使用换行符、空格和制表符进行格式化。这些格式将丢失。

我们提供了一个短语级别的标记，它是两者之间的混合。通过使用双引号或三引号（而不是单引号）告诉 QuickBook 使用预先格式化的代码块。示例

``
    #include <iostream>

    int main()
    {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
``

或者

```
    #include <iostream>

    int main()
    {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }
```

将生成

#include <iostream>

int main()
{
    std::cout << "Hello, World!" << std::endl;
    return 0;
}

如果文档包含多种源代码，则可以在处理文档时动态更改源代码模式。默认情况下，所有 QuickBook 文档最初都处于 C++ 模式，尽管可在 Document 部分中设置另一个初始值。

要更改源代码模式，请使用 [source-mode] 标记，其中 source-mode 是受支持的模式之一。例如，

Python's [python] `import` is rather like C++'s [c++] `#include`. A
C++ comment `// looks like this` whereas a Python comment [python]
`# looks like this`.

将生成

Python 的 import 类似于 C++ 中的 #include。C++ 注释 // 看起来像这样，而 Python 注释 #看起来像这样。

Quickbook 1.7 引入了 ! 元素，该元素可用来设置后面元素的源代码模式

[teletype]
Example in C++: [!c++] `int main() {}`,
example with no highlighting: `int main() {}`.

将生成

C++ 代码示例： int main() {}，不带高亮的示例： int main() {}。

要更改整个段落的源代码模式，请在段落前单独以一行放置 ! 元素

[!c++]
`int main() {}` is highlighted as C++, as is `//example`.

[!c++] `int main() {}` is also highlighted as C++,
but `//example` isn't.

生成

int main() {} 突出显示为 C++ 代码， //example 也是如此。

int main() {} 也突出显示为 C++ 代码，但 //example 却不会。

! 元素还可用于设置块和部分的源代码模式。例如

[!python]
[section:python Section in which all code samples use python]

[/...]

[endsect:python]

[!c++]
[section:cpp Section in which all code samples use C++]

[/...]

[endsect:cpp]

或设置表格的源代码模式

[!teletype]
[table
    [[code][meaning]]
    [[`+`][addition]]
]

	请注意
	源代码模式字符串采用小写形式。

[br]

	警告
	[br] 会生成无效的 DocBook。它看起来工作正常，但还是可能存在问题，尤其是在使用另一种 DocBook 处理器时。

[#named_anchor]

命名锚是一个钩子，可以由文档中其他位置的链接引用。然后，你可以通过 [link named_anchor Some link text] 引用锚。请参阅 锚链接、Section 和 Heading。

这些锚是全局的，可以从 quickbook 文档的任何位置访问。请小心，谨防与其他部分的锚发生冲突。

[@https://boost.ac.cn this is [*boost's] website....]

将生成

这是 boost 网站....

链接文本就是链接本身的 URL 链接很常见。示例

see http://spirit.sourceforge.net/

因此，当链接标记中没有文本时，它表示 URL。示例

see [@http://spirit.sourceforge.net/]

将生成

参阅 http://spirit.sourceforge.net/

BoostBook 还支持一个自定义 URL 方案，以便链接到 Boost 分发版中的文件

[@boost:/libs/spirit/index.html the Boost.Spirit documentation]

将生成： Boost.Spirit 文档

请注意，只有在使用 BoostBook 且仅用于链接时才可用——无法将其用于图像。

你可以通过以下方式在文档内添加链接

[link document_id.section_id.normalized_header_text The link text]

有关更多详情，请参阅部分 部分 和 标题。

另外，您可以像如下形式内部链接到一个 XML refentry

[link xml.refentry The link text]

这会转换成 <link linkend="xml.refentry">链接文本</link>。

类似 URL，链接文本是可选的。如果未出现，链接文本将自动成为 refentry。例如

[link xml.refentry]

这会转换成 <link linkend="xml.refentry">xml.refentry</link>。

如果您想在引用部分链接到函数、类、成员、枚举、概念、全局内容或标题中，您可以使用

[funcref fully::qualified::function_name The link text]
[classref fully::qualified::class_name The link text]
[memberref fully::qualified::member_name The link text]
[enumref fully::qualified::enum_name The link text]
[macroref MACRO_NAME The link text]
[conceptref ConceptName The link text]
[headerref path/to/header.hpp The link text]
[globalref fully::qualified::global The link text]

同样，链接文本是可选的。如果未出现，链接文本将自动成为函数、类、成员、枚举、宏、概念、全局内容或标题名称。例如

[classref boost::bar::baz]

会得到“boost::bar::baz”作为链接文本。

在我们不想做任何处理时，转义标记会被使用。

'''
escape (no processing/formatting)
'''

转义允许我们将 XML 标记传递至 BoostBook 或 DocBook。例如

'''
<emphasis role="bold">This is direct XML markup</emphasis>
'''

这是直接的 XML 标记

	重要
	使用转义时要小心。文本必须满足 BoostBook/DocBook 语法。

反斜杠可以用来转义单个标点符号。反斜杠后直接出现的标点符号将传递而不做任何处理。当我们需要转义 QuickBook 标点符号（如 [ 和 ]）时，这非常有用。例如，您如何转义三引号？简单： \'\'\'

\n 有特殊含义。它用于产生换行符。

	警告
	\n 现在已弃用，请使用 [br] 取代。不过，要谨慎使用，因为它会生成无效的 DocBook

转义的空格： \ 也有特殊含义。转义的空格会从输出中移除。

您可以通过使用 \u 后跟其 4 位十六进制代码或通过使用 \U 后跟其 8 位十六进制代码来输入任意 16 位 Unicode 字符，或输入 32 位字符。例如

\u03B1 + \u03B2

将生成

[$image.jpg]

从版本 1.5 开始，您还可以使用 DocBook imagedata 属性

[$image.jpg [width 200in] [height 200in]]

从版本 1.3 开始，QuickBook 支持脚注。只需将脚注文本放入 [footnote] 块中，文本就会被放置在当前页面的底部。例如，此

[footnote A sample footnote]

将生成此内容^[35].

__a_macro_identifier__

有关详细信息，请参见 宏。

[a_template_identifier]

有关详细信息，请参见 模板。

像 C++ #ifdef 一样，您可以根据宏是否存在来生成短语。示例

[? __to_be__ To be or not to be]

在这里，仅当已预先定义宏符号 __to_be__ 时，才会生成短语“To be or not to be”。由于我们尚未定义 __to_be__，所以上述短语不会执行任何操作。现在，我们定义符号

[def __to_be__]

[? __to_be__ To be or not to be]

生成结果如下

To be or not to be

在 quickbook 1.7 中，如果未定义宏，您可以生成输出

[?! __to_be__ Not to be]