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）页面来记录问题和答案。这对用户和维护者来说都是非常有价值的文档，因此应从一开始就提供常见问题页面。如果没有明显会成为常见问题的问题，初始页面可能只指示尚无常见问题。此空占位符有助于向用户表明您计划在出现常见问题时解决它们。
常见问题页的页面索引应包含文档中所有问题的列表。实际问题条目应使用标题标签格式化问题，并使用标准段落格式格式化答案。这提供了一种易于阅读的清晰演示文稿。
提供了一个常见问题页模板以供使用。
参考书目页用于记录与文档中对外部资源的引用相关的任何参考书目信息。文档中使用括号引用，链接到参考书目页中的条目。参考书目条目提供有关外部资源的详细信息，如果资源在线可用，则可能包含指向该资源的超链接。编写参考书目有几种正式样式。您可以使用任何您想要的样式，但可以在此处参考一种更好的样式。
由于参考书目页应仅包含参考书目信息，因此无需页面索引。
提供了一个参考书目页模板以供使用。
致谢页用于给予应得的荣誉。当个人对设计或实施提供意见时，或者当您利用他人的工作时，您应该感谢他们。这是您希望他人向您表达的礼貌，因此您应该努力在自己的文档中感谢其他所有人的努力。
由于致谢页应仅包含致谢列表，因此无需页面索引。
提供了一个致谢页模板以供使用。
头文件参考页是文档中最重要的页面。它们记录所有库头文件，包括其中定义的所有宏、值、类型、类、函数和对象。通常，在编写这些页面的内容时，遵循文档结构中的准则可能会有所帮助。
像大多数内容页面一样，头文件参考页应包含页面索引。
提供了一个头文件参考页模板以供使用。
您的许多页面会频繁使用某些页面布局概念。本节概述了在为文档设计每个布局概念时可以遵循的一些通用准则。
页面横幅位于页面顶部，提供有关页面内容的快速信息。这包括 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> 标记）列表。当您需要一组没有任何逻辑顺序的项目（例如由库定义且可以用作模板参数的数据类型列表）时，可以使用无序列表。当项目集合必须按逻辑顺序分组时，可以使用有序列表，例如枚举操作逻辑执行的步骤时。当列表不仅包含没有逻辑顺序的项目，还包含项目的定义/描述/等时，可以使用定义列表。一个很好的例子是 文档结构 中描述的函数规范。
图形应尽量少用，如果使用的话。图形图像会极大地影响许多人的下载时间，这可能会 discourage 用户阅读文档。如果您需要图形图像来帮助说明文档中的某些内容，请考虑仅提供文档中图像的链接，而不是将其直接嵌入文本中。如果要在文档文本中包含图像，则应在 <img> 标记中指定图像的大小，以便用户的浏览器在加载图像之前优化文本的格式。
应避免在 HTML 文本中使用不间断空格 ( )。通常，有更合适的格式化文档的方法，例如使用列表结构或将缩进指定为样式属性或在层叠样式表中指定缩进。
层叠样式表允许您将一些高级格式样式应用于 HTML 文档。更重要的是，它们允许您更改单个文件中的格式并影响使用样式表的所有页面。与其努力在 HTML 中生成特定格式，不如在样式表中指定格式通常更简单、更灵活。
使用层叠样式表来格式化 HTML 的概念是一个非常好的主意，以至于将其应用于整个 Boost 网站可能会有所裨益。当然，我们不能要求这样做（如果 Boost 要求提交的内容包含此类琐碎内容，则可能会 discourage 许多程序员做出贡献）。但是，仍然提供了一个“标准”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）
