Boost C++ 库

在 Quickbook 1.5 中，如果您包含一个以 docinfo 块开头的文件，它将被忽略，并且该文件将在原地展开。在 Quickbook 1.6 中，它被视为嵌套在当前位置的文档。因此，如果它具有 'article' docinfo 块，则会使用 boostbook 'article' 标签。

它还在很大程度上生成与文件单独转换时相同的标记 - 例如，生成相同的 ID，使用 docinfo 块中指定的语言版本处理文档。如果未指定语言，它将使用默认语言 (1.1)，而不是包含它的文档的版本。这可能看起来令人惊讶，但这是必需的，以便 Quickbook 以与单独转换时相同的方式转换它。

因此，在大多数情况下，包含 docinfo 的文件就像 xinclude，除了几个不同之处。在父文档中定义的模板和宏在包含的文档中使用，并且 ID 生成器会重写多个文档之间冲突的 ID。

如果包含的文档没有 docinfo 块，则它像以前一样包含。

您现在可以在 docinfo 块的文本字段中展开宏。在顶部 docinfo 块中，仅预定义的宏可用，但在嵌套文档中，父文档中定义的宏也可用。

这里有一个小错误 - 这会泄露到旧版本中的 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 无法链接到。

如前所述，更改 ID 生成器将破坏使用旧语言版本编写的文档中的链接。因此，为了简化过渡，使用了“兼容模式”，这只需要 docinfo 中的一个额外属性，例如，如果您要将 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 块。如果您有，则使用文件的 Quickbook 版本，如果您没有，即使您指定了 Quickbook 版本，它也会继承父级的兼容模式。这是正确的做法 - 在文档中混合兼容模式是有问题的。允许在 docinfo 块之外指定它们实际上可能是一个错误。

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

标题现在可以被赋予显式 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 文件将位于哪个目录中，因此不可能使用相对链接。这可以通过向 document 标签添加 xml:base 属性来解决。为此，请在文档的 docinfo 块中使用新的 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 docinfo 属性可能永远不会像 docbook 属性那样丰富。为了允许更多 Quickbook 不支持的灵活标记，可以在 docinfo 块中包含转义的 docbook

[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 属性混合用于相同的信息将无法正常工作。

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

* 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 转义是双反斜杠“\\”；即转义的反斜杠。