Boost 对库提交者的 HTML 文档设计没有要求。如果您提交的库已经存在 HTML 文档，或者可以轻松转换为 HTML 格式的文档，则无需阅读本文档。但是，如果您尚未编写文档，或者您预计需要翻译以不易转换为 HTML 的格式编写的文档，那么本文档可以为您提供有关如何使用 HTML 编写文档的大量信息。
本文档在多个地方假设您正在编写文档以符合 文档结构 文档中描述的结构。不要求您的文档内容遵循这些指南，但它们提供了一种有效的方式来以简洁而精确的方式传达库的技术规范，这对于许多 Boost 用户来说是熟悉的。
本文档还包含指向 HTML 模板文件 的链接，这些模板文件可用于快速开发库提交的文档。这些模板遵循此处和 文档结构 文档中提出的指南。
大多数 HTML 文档项目将包含一些常用页面。下面提供了这些常用页面的一般指南。
索引页是用户浏览文档时呈现的第一个页面。通常，此页面不应包含任何实际内容，而应包含指向特定内容的链接列表。至少，此列表应包含指向文档中包含的每个 HTML 页面的链接。可选地，可以为单个页面提供子列表，链接到页面内的特定主题。这些子列表应形成基于用于特定主题的标题标签级别的“树”层次结构。为每个页面包含这样的子列表可能会使索引相当长，并且由于每个页面都应包含其自己的 页面索引，因此如果避免使用这样的子列表，可能会使文档的导航更容易。但是，此指南有一个例外：参考文档应包含指向库中每个头文件的链接，以及一个子列表，其中包含指向头文件中找到的每个宏、值、类型、类、函数和对象（请参阅 文档结构）的链接。用户并不总是确定这些内容包含在哪个头文件中，因此索引中的这种结构允许轻松导航参考文档。
索引列表通常应使用 HTML “定义列表” (<dl> 和 <dt> 标签) 构建。定义列表没有项目符号或有序规范，并且产生比无序列表 (<ul> 和 <li> 标签) 或有序列表 (<ol> 和 <li> 标签) 更简洁的布局。如果您选择使用常用的 Boost 样式表，则应向 <dl> 标签添加 class="index" 属性/值对。
提供了索引页 模板 供使用。
概述页用于向读者介绍库。它应给出库用途的高级概述，并向读者介绍他们可能不熟悉的任何概念。这也可以是放置一些“轻量级”理由的合适位置，尽管更彻底地介绍任何理由最好放在 理由页 中。
与大多数内容页面一样，概述页应包含 页面索引。
提供了概述页 模板 供使用。
定义页用于提供用户可能不熟悉的术语的定义列表。
定义列表通常应使用 HTML “定义列表” (<dl> 和 <DT> 标签) 构建。定义列表没有项目符号或有序规范，并且产生比无序列表 (<UL> 和 <li> 标签) 或有序列表 (<ol> 和 <li> 标签) 更简洁的布局。如果您选择使用常用的 Boost 样式表，则应向 <dl> 标签添加 class="definition" 属性/值对。
由于此页面的内容应仅包含定义列表，因此它不应具有 页面索引。
提供了定义页 模板 供使用。
理由页用于提供库设计背后理由的详细描述。此信息有助于用户了解库的设计方式，并可能减少许多常见问题的频率。有关为什么理由很重要的更好描述，请参阅一般提交指南中的 理由的理由。
与大多数内容页面一样，理由页应包含 页面索引。
提供了理由页 模板 供使用。
配置信息页用于记录库使用的配置宏。这些宏属于三个组之一：库实现者在 <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 复制)
