Boost 对库提交者 HTML 文档的设计没有要求。如果您要提交的库已经存在 HTML 或易于转换为 HTML 的形式的文档，则您无需阅读本文档。但是，如果您尚未编写文档，或者如果您预计必须翻译以非 HTML 格式编写的文档，则本文档可以为您提供大量有关如何使用 HTML 编写文档的信息。
本文档在几个地方假设您正在编写文档以符合 文档结构 文档中描述的结构。您的文档内容没有必要遵循这些准则，但它们提供了一种有效的方式，以简洁、精确的方式传达库的技术规范，这种方式为许多 Boost 用户所熟悉。
本文档还包含指向 HTML 模板文件 的链接，这些文件可用于快速开发库提交的文档。这些模板遵循此处和 文档结构 文档中介绍的准则。
大多数 HTML 文档项目将包含一些常见页面。以下提供了有关这些常见页面的一般准则。
索引页是用户浏览文档时呈现的第一个页面。通常，此页面不应包含任何实际内容，而是包含指向特定内容的链接列表。至少，此列表应包含指向文档中包含的每个 HTML 页面的链接。可选地，可以为各个页面提供子列表，这些子列表链接到页面内的特定主题。这些子列表应根据用于特定主题的标题标签级别形成“树”层次结构。为每个页面包含此类子列表可能会使索引变得很长，并且由于每个页面都应包含自己的 页面索引，因此避免此类子列表可能会使文档导航更容易。但是，此准则有一个例外：参考文档应包含指向库中每个头文件的链接以及包含指向头文件中找到的每个宏、值、类型、类、函数和对象的子列表（请参阅 文档结构）。用户并不总是确定这些内容可能包含在哪个头文件中，因此索引中的此结构允许轻松浏览参考文档。
索引列表通常使用 HTML “定义列表”（<dl> 和 <dt> 标签）构建。定义列表没有项目符号或有序规范，并且比无序列表 (<ul> 和 <li> 标签) 或有序列表 (<ol> 和 <li> 标签) 生成更简洁的布局。如果您选择使用常见的 Boost 样式表，则应将 class="index" 属性/值对添加到 <dl> 标签中。
提供了一个索引页面 模板 供使用。
概述页用于向读者介绍库。它应该提供有关库目的的高级概述，并向读者介绍他们可能不熟悉的任何概念。这可能也是一些“轻度”原理的适当位置，尽管更彻底地展示任何原理将更适合放置在 原理页 中。
与大多数内容页面一样，概述页应包含 页面索引。
提供了一个概述页面 模板 供使用。
定义页用于提供用户可能不熟悉的术语的定义列表。
定义列表通常使用 HTML “定义列表”（<dl> 和 <DT> 标签）构建。定义列表没有项目符号或有序规范，并且比无序列表 (<UL> 和 <li> 标签) 或有序列表 (<ol> 和 <li> 标签) 生成更简洁的布局。如果您选择使用常见的 Boost 样式表，则应将 class="definition" 属性/值对添加到 <dl> 标签中。
由于此页面的内容应仅包含定义列表，因此它不应包含 页面索引。
提供了一个定义页面 模板 供使用。
原理页用于提供有关库设计的原理的冗长描述。这些信息可以帮助用户了解库为何以这种方式设计，并可能减少许多常见问题的频率。有关原理重要性的更详细说明，请参阅一般提交准则中的 原理原理。
与大多数内容页面一样，原理页应包含 页面索引。
提供了一个原理页面 模板 供使用。
配置信息页用于记录库使用的配置宏。此类宏属于以下三类之一：由库实现者使用的宏（在 <boost/config.hpp> 中定义）、由库用户使用的宏以检测平台配置信息以及由库用户定义的宏以配置库行为。
与大多数内容页面一样，概述页应包含 页面索引。
提供了一个配置页面 模板 供使用。
随着库的成熟，用户将对库的使用产生疑问。用户经常会一遍又一遍地问同样的问题。与其每次都回答这个问题，不如使用常见问题解答 (FAQ) 页面来记录问题和答案。这对于用户和维护人员来说都是如此宝贵的文档，因此应从一开始就提供一个 FAQ 页面。如果没有任何明显会成为 FAQ 的问题，那么初始页面可能只是表示还没有 FAQ。这个空占位符有助于向用户表明您计划在出现任何 FAQ 时解决这些问题。
FAQ 页面的 页面索引 应包含文档中包含的所有问题的列表。实际问题条目应以标题标签中的问题和标准段落格式的答案进行格式化。这提供了一种简洁、易于阅读的展示方式。
提供了一个常见问题解答页面 模板 供使用。
参考书目页用于记录与文档中对外部资源的引用相关的任何书目信息。文档中使用括号内的引用，这些引用链接到参考书目页面的条目。书目条目提供有关外部资源的详细信息，如果该资源可在线获取，则可能包含指向该资源的超链接。有几种用于编写参考书目的正式样式。您可以使用您想要的任何样式，但要考虑使用的一种较好的样式可以参考 此处。
由于参考书目页应仅包含书目信息，因此无需 页面索引。
提供了一个参考书目页面 模板 供使用。
致谢页用于对应得的人表示感谢。当个人对设计或实现提供意见，或者当您使用其他人的作品时，您应该感谢他们。这是一份礼貌，您希望其他人也给予您，因此您应该努力在自己的文档中感谢所有其他人的努力。
由于致谢页应仅包含致谢列表，因此无需 页面索引。
提供了一个致谢页面 模板 供使用。
头文件参考页是文档中最重要的页面。它们记录所有库头文件，包括在其中定义的所有宏、值、类型、类、函数和对象。一般来说，在编写这些页面的内容时，遵循 文档结构 中的准则可能会有所帮助。
与大多数内容页面一样，头文件参考页应包含 页面索引。
提供了一个头文件参考页 模板 供使用。
在许多页面中，将经常使用某些页面布局概念。本节概述了在设计文档的每个布局概念时可以遵循的一些一般准则。
页面横幅位于页面的最顶部，并提供有关页面内容的快速信息。这包括 Boost 徽标，它向读者表明此页面是 Boost 网站的一部分，文档标题（通常是库名称）和页面标题。Boost 徽标应在索引页上链接到 Boost 主页，而在所有其他页面上链接到索引页。这允许用户轻松地在 Boost 网站和文档中导航。HTML 页面的 <title> 标签应包含文档标题和页面标题，用连字符隔开。
页面标题应使用<hr>标签与页面其余部分分隔开。这有助于清楚地将实际内容与标题信息分隔开，并生成更整洁的文本。
页面索引用于快速导航到页面上文档的各个部分，如果存在，应位于页面标题下方。
索引列表通常应使用 HTML“定义列表”（<dl> 和 <DT> 标签）构建。定义列表没有项目符号或排序规格，比无序列表（<UL> 和 <li> 标签）或有序列表（<ol> 和 <li> 标签）产生更整洁的布局。如果您选择使用 Boost 样式表，则应在 <dl> 标签中添加 class="page-index" 属性/值对。
大多数页面都应包含页面索引。
页面的实际文档内容将根据各个页面的具体需求进行格式化，如果存在，应放在页面索引之后，否则放在页面标题之后。一般来说，文档内容将采用段落文本的形式，位于节标题下方。
脚注可以在页面的文档中使用。在文档内容中，脚注引用应采用括号中的脚注编号形式（括号使读者更容易单击超链接）超链接到页面文档内容底部的实际脚注。您可以使用<sup>标签来格式化此类脚注编号，或者，最好使用 CSS 样式类来将编号区分开来，使其成为脚注，而不是实际文本的一部分。如果您选择使用常用的Boost 样式表，则为此目的定义了footnote类。
每个页面底部应包含一些修订信息，指示页面上次修订的时间。该信息应使用<hr>标签与上面的页面其余部分分隔开。可以使用以下 HTML 代码片段来跟踪此修订信息（此代码使用 Boost 网站上存在的一些服务器组件来自动跟踪修订日期，而无需手动编辑日期文本）
<hr> <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 01 January, 2001 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> </p>
页面的最底部应包含适用于文档的任何版权信息。
本节提供使用 HTML 格式化文档的一般指南。对各种“常见页面”的描述提供了格式化文档特定部分的具体细节，这些细节应优先于这些指南。
文档中的代码应放在<code></code> 或 <pre></pre> 标签中。对于与其他文本内联的代码，您使用<code></code> 标签，而<pre></pre> 标签用于代码“块”。如果级联样式表用于为这些标签指定格式，则应使用固定宽度的无衬线字体。这确保代码易于与其余文本区分开来。将 <pre></pre> 标签的样式设置为缩进文本也可能有利，以帮助将代码块与其他结构化 HTML 块分隔开来。Boost 样式表 指定了这些标签的格式。
注意：“代码”包括变量名、函数名等。
列表应在 HTML 中构建为无序（<UL> 和 <li> 标签）、有序（<ol> 和 <li> 标签）或定义（<dl> 和 <DT> 标签）列表。当您需要一组没有逻辑顺序的项目时，使用无序列表，例如库定义的数据类型列表，这些类型可用于模板参数。当项目集合必须按逻辑顺序分组时，使用有序列表，例如枚举操作逻辑执行的步骤。当列表不仅包含没有逻辑顺序的项目，还包含项目的定义/描述/等时，使用定义列表。一个很好的例子是文档结构中描述的函数规范。
图形应该非常节俭地使用，如果有的话。图形图像会极大地影响许多人的下载时间，这可能会阻止用户阅读文档。如果您需要图形图像来帮助说明文档中的某些内容，请考虑只提供文档中图像的链接，而不是直接将其嵌入文本中。如果要将图像包含在文档的文本中，则应在<img> 标签中指定图像的大小，以便允许用户的浏览器在图像加载之前优化文本的格式。
应避免在 HTML 文本中使用不间断空格（ ）。通常，有更合适的方法来格式化文档，例如使用列表结构或将缩进指定为样式属性或在级联样式表中。
级联样式表允许您对 HTML 文档应用一些高级格式样式。更重要的是，它们允许您更改单个文件中的格式，并影响使用样式表的所有页面。与其费力地在 HTML 中生成特定格式，不如在样式表中指定格式，这通常更容易也更灵活。
使用级联样式表来格式化 HTML 的概念是一个非常好的主意，以至于将其应用于整个 Boost 网站可能是有益的。当然，我们不能要求这样做（如果 Boost 要对提交的内容提出这样的琐碎要求，那么许多程序员可能会不愿做出贡献）。但是，无论如何都提供了一个“标准”Boost 样式表（https://boost.ac.cn/boost.css），以便贡献者可以快速轻松地生成清晰一致的文档，如果他们愿意，这些文档可以反映 Boost 的“品牌”。如果稍后决定更新 Boost 的“品牌”，则可以在这个单个文件中完成，使用样式表的所有文档都将自动更新。
Boost 提供的样式表不仅为许多标准标签指定样式，还指定了几个样式“类”。类是为给定标签指定的，而不是应用于给定标签类型的所有实例。以下是 Boost 样式表中指定的类的列表以及何时使用它们的描述
与其手动编码每个 HTML 页面，不如使用 HTML“模板”。以下列表提供了在编写对 Boost 的贡献的文档时可能使用的模板的链接。这些模板中提供的链接假定文件将驻留在boost/libs/library/doc 的“传统”目录层次结构中。如果文件驻留在其他位置，则可能需要对其进行更正。
注意：由于这些“模板”只是 HTML 页面，因此只需单击下面的链接即可在浏览器中加载模板。您需要使用特定于浏览器的 方法来下载文件，而不是将它们加载到浏览器中（例如，在大多数 Windows 浏览器上，您可以右键单击链接并从上下文敏感菜单中选择相应的命令）。
修订2006 年 12 月 4 日
版权所有 © 2001 William E. Kempf
根据 Boost 软件许可证 1.0 版发布。 （请参阅随附文件 LICENSE_1_0.txt 或复制到 https://boost.ac.cn/LICENSE_1_0.txt）
