Boost C++ 库

在 Quickbook 1.5 中，如果您包含以文档信息块开头的文件，它将被忽略，并且文件将在适当位置展开。在 Quickbook 1.6 中，它被视为嵌套在当前位置的文档。因此，如果它有一个“article”文档信息块，则使用 Boostbook“article”标签。

它生成的大部分标记也与单独转换文件时生成的标记相同 - 例如，生成相同的 ID，使用文档信息块中指定的语言版本处理文档。如果未指定语言，它将使用默认值 (1.1)，而不是包含它的文档的版本。这似乎令人惊讶，但这是必需的，以便 Quickbook 将以与单独转换相同的方式转换它。

因此，在大多数情况下，包含文档信息的包含类似于 xinclude，除了一些差异之外。在父文档中定义的模板和宏在包含的文档中使用，并且 ID 生成器重写了多个文档之间冲突的 ID。

如果包含的文档没有文档信息块，则它会像以前一样包含在内。

您现在可以在文档信息块的文本字段中展开宏。在顶级文档信息块中，只有预定义的宏可用，但在嵌套文档中，父文档中定义的宏也可用。

这里有一个小错误 - 这会泄漏到旧版本的 license 和 purpose 字段中，但由于只有预定义的宏可用，因此不太可能破坏任何现有文档。所以我宁愿不通过修复它来使代码进一步复杂化。

一个长期存在的 Quickbook 错误是宏的作用域由文件限定，而模板则不是。因此，您可以在单独的文件中定义模板并包含它们，但不能包含宏。这已得到修复，因此在一个文件中定义的模板不会“泄漏”到另一个文件中。

但这意味着无法在单独的文件中定义模板 - 这一个有用的功能。为此，import 元素已适用于支持 Quickbook 文件。如果导入了 Quickbook 文件，则其中定义的模板和宏将添加到当前作用域，但该文件中包含的其他内容均未使用。这可以用于创建模板和宏库文件。这与导入代码段的现有语义相匹配。

导入模板时，它们绑定到定义它们的文件的语言版本。这意味着如果您将它们导入到具有不同版本的文件中，它不会改变它们的解释方式。但是，正如我们稍后将看到的那样，生成的 Boostbook 略有不同。

由于 import 现在支持 Quickbook 文件，include 也支持源文件。它包含代码段之外的注释中包含的任何 Quickbook。文件中的代码段可用于在文件中展开，但其作用域限定于该文件。其方式与在包含的 Quickbook 文件中限定模板和宏的作用域的方式完全相同。

Quickbook 1.5 中的 ID 生成有点问题，但如果不进行版本切换就无法修复，因为它会破坏现有文档。例如，在 Quickbook 1.5 中，当您包含一个 Quickbook 文件时，它会停止使用文档信息中的显式 ID，并从文档标题生成一个新的 ID 来代替。

Quickbook 1.6 中的 ID 生成器也以其他一些方式得到了改进。从章节标题、表格标题等生成 ID 时，它始终使用 Quickbook 源代码而不是生成的 Boostbook 来生成 ID。然后，它会稍微清理 ID，修剪前导和尾随下划线，并将多个下划线替换为单个下划线。然后，如果新生成的部分 ID 长于 32 个字符，它将截断它。

虽然新的 ID 生成器通常会创建更好的 ID，但它更有可能生成重复项，因此 Quickbook 需要更好地处理重复项。当有多个相同的 ID 时，Quickbook 根据优先级列表选择一个使用 - 首选锚点，然后是显式文档和章节 ID，然后是其他显式 ID，最后是生成的 ID。然后，文档中任何其他显式 ID 都会添加数字以避免重复 - 首先是按它们出现的顺序排列的显式 ID，然后是生成的 ID。意外与显式 ID 冲突的生成的 ID 永远不会更改显式 ID。

较旧的语言版本仍然生成它们始终生成的相同 ID，但重复 ID 除外，它们使用新机制处理 - 这不是一个重大更改，因为无法链接到重复 ID。

如前所述，更改 ID 生成器将破坏使用旧语言版本编写的文档中的链接。因此，为了简化转换，使用了“兼容模式”，这只需要在文档信息中添加一个额外的属性，例如，如果您要将 1.5 文档转换为 1.6

[article Document
[quickbook 1.6]
[compatibility-mode 1.5]
]

这意味着该文档将被解析为 1.6，使用所有新功能，但 ID（可能还有其他标记）将按照 1.5 文档的方式生成。

当生成使用与当前文档不同的语言版本编写的模板时，也会隐式使用兼容模式。因此，模板将以其编写的版本进行解析，但会生成与当前文档兼容的 Boostbook。

现在可以在文件开头使用 quickbook 和 compatibility-mode 标签。在文档信息块之前或没有文档信息块的情况下。这对于仅包含模板的文件很有用，这些文件实际上不需要文档信息块。

如果您未指定compatibility-mode（兼容模式），则行为取决于您是否具有文档信息块 (docinfo block)。 如果有，则使用文件的 Quickbook 版本；如果没有，则继承父级的兼容模式，即使您指定了 Quickbook 版本也是如此。 这样做是正确的 - 在文档中混合兼容模式会产生问题。 在文档信息块之外指定它们实际上可能是一个错误。

此更改也已向后移植到旧版本。 因此，当从旧版本包含文件时，可以设置包含文件的版本（旧版本忽略包含文件中的文档信息）。

现在可以为标题指定显式 ID。

[heading:id A heading with an explicit id]

在 1.6 版本中，Quickbook 在解析标点符号方面更加一致。 现在，链接、锚点、表格标题、图像属性等都支持转义。 与此同时，Quickbook 现在对未转义的括号更加严格。 它们仍然可以使用，但需要匹配，否则会出现错误。

由于 Quickbook 现在会匹配方括号，因此它将修复一些错误的解析。 例如，[*[bold]] 过去解析为 [bold - 请注意，右方括号不是粗体，现在它解析为 [bold]。 在这种情况下，这只是一个细微的视觉差异，但它可能会导致奇怪的问题，例如嵌套在表格单元格中时。

表格标题现在被解析为短语，因此允许使用一些标记。

[table [*bold title]]

这是一个带有粗体标题的空表。 标题不再以换行符结尾，而是以右方括号或两个左方括号结尾 - 您在表格单元格的开头会看到这两个左方括号，所以现在这样可行。

[table Simple[[heading 1][heading 2]][[cell 1][cell 2]]]

在转义的 Boostbook 中使用 xi:include 标签时，一个问题是您通常不知道 Boostbook 文件将在哪个目录中，因此无法使用相对链接。 这可以通过在文档标签中添加 xml:base 属性来解决。 为此，请在文档的文档信息块中使用新的 xmlbase 属性。 例如，要使转义的 xi:include 相对于文件的目录。

[library Library documentation
[quickbook 1.6]
[xmlbase .]
]

xinclude 元素中的任何路径都将相应地重写。 请注意，大多数文档不需要这个属性，并且可能不应该使用它。 仅当您完全确定需要它时才使用它。

有一个新的模板声明和参数解析器，它可以更好地理解转义文本和括号文本。 不幸的是，它不理解元素名称，因此在某些情况下可能会出错。 例如：

[template doesnt_work[]
[ordered_list
    [`code phrase`]
]
]

在这种情况下，它会认为 [\` 是一个模板调用并给出解析错误。 要解决此问题，请在代码短语前放置一个转义空格。

[template works[]
[ordered_list
    [\ `code phrase`]
]
]

Quickbook 1.6 中添加的新元素：

以前，如果您在错误的上下文中使用元素，它只会未经处理，这令人惊讶。 人们常常没有意识到他们的元素没有被处理。 所以现在这是一个错误。

如果短语元素的主体无法解析，则将直接使用未处理的内容。 现在将其更改为硬错误。

1.7 引入了一种新的 ! 元素类型，用于设置单个实体的源模式，而无需更改其他源模式。 这可以用于代码块和其他元素。 例如：

[!c++]
    void foo() {};

[!python]```def foo():```

它还可以用于设置元素的源模式：

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

当在节之前使用时，它会设置整个节的源模式。

如果它出现在段落的开头，则仅当有换行符时才会用于整个段落，例如：

[!c++]
A declaration `void foo();` and a definition `void foo() {}`.

目前，标注只能在代码片段中使用。 1.7 增加了对普通代码块的支持。 使用与代码片段相同的语法，标注描述出现在代码块的紧后面。

Quickbook 文档信息属性可能永远不会像 Docbook 属性那样丰富。 为了允许 Quickbook 不支持的更灵活的标记，可以在文档信息块中包含转义的 Docbook。

[article Some article
[quickbook 1.7]
'''<author>
    <firstname>John</firstname>
    <surname>Doe</surname>
    <email>[email protected]</email>
</author>'''
]

转义的 Docbook 始终放置在文档信息块的末尾，因此不应假设它会与 Quickbook 生成的标记交错。 将 Quickbook 和 Docbook 属性混合用于相同的信息将无法正常工作。

现在可以在列表中使用段落和块元素。

* Para 1

  Para 2
  * Nested Para 1

    Nested Para 2

        Code block
  Para 3

生成：

支持在链接值、锚点、角色和包含项中调用模板。 这有时会有一些变化，尤其是在当前允许使用空格的地方，因此我可能会尝试在需要的地方使用稍微不同的语法。 我想我还需要添加一些验证，因为解析器可以允许比某些旧解析器更多的符号。

现在可以将列表标记放置在嵌套块中，例如在表格、变量列表等中。 不幸的是，缩进代码块更棘手，因为这些块的内容通常已经缩进。 在这种情况下，不支持缩进代码块比尝试为边缘情况制定合理的行动更容易。 如果您想在这种情况下使用代码块，您仍然应该能够使用显式标记。

现在可以在短语模板中使用块元素，但不允许使用段落分隔符，因此这是一个错误：

[template paras[] Something or other.

Second paragraph.]

如果短语模板仅包含块元素，则它实际上与块模板无法区分。 因此，您将从以下代码获得相同的输出：

[template foo[] [blurb Blah, blah, blah]]

和：

[template foo[]
[blurb Blah, blah, blah]
]

如果短语模板将短语内容与块元素混合使用，它将生成输出，就好像它是内联扩展的一样。

现在可以使用文件引用的 glob 模式一次包含多个文件。

[include sub/*/*.qbk]
[include include/*.h]

所有匹配的文件和中间目录都将匹配并包含在内。 glob 模式可以是 "*" 用于匹配零个或多个字符，"?" 用于匹配单个字符，"[<c>-<c>]" 用于匹配字符类，"[^<char>-<char>]" 用于排除匹配字符类，"\\" 用于转义然后匹配的 glob 特殊字符，其他任何内容都与字符匹配。

	注意：
	由于文件引用中的转义，“\\” glob 转义是双反斜杠 "\\"；即转义的反斜杠。