为 Boost 编写文档HTML 设计 |
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 样式表，则应将 class="page-index" 属性/值对添加到 <dl> 标签。
大多数页面都应包含页面索引。
页面的实际文档内容将根据各个页面的特定需求进行格式化，并且如果存在页面索引，则应放在页面索引之后，如果不存在，则放在页面横幅之后。通常，文档内容将以段落文本的形式出现在章节标题下方。
可以在页面的文档中使用脚注。在文档内容中，脚注引用应采用括号内的脚注编号（括号使读者更容易点击超链接）的形式，超链接到页面文档内容底部的实际脚注。您可以选择使用 <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 复制）
