为 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>` 标签应包含文档标题和页面标题，用连字符分隔。
页面横幅应使用 `
页面索引用于快速导航到页面上的各种文档部分，并在存在时应位于页面横幅下方。
索引列表通常应使用 HTML 的“定义列表”（`<dl>` 和 `<DT>` 标签）构建。定义列表没有项目符号或有序规范，并且比无序列表（`<UL>` 和 `<li>` 标签）或有序列表（`<ol>` 和 `<li>` 标签）产生更干净的布局。如果您选择使用 Boost 样式表，则应将 `class="page-index"` 属性/值对添加到 `<dl>` 标签。
大多数页面应包含页面索引。
页面的实际文档内容将根据各个页面的具体需求进行格式化，如果存在页面索引，则应放在页面索引之后，如果不存在，则放在页面横幅之后。总的来说，文档内容将采取段落文本的形式，位于节标题下方。
可以在页面的文档中使用脚注。在文档内容中，脚注引用应采用括号内的脚注编号（括号使其更容易读者点击超链接）的形式，链接到页面文档内容底部的实际脚注。您可以选择使用 `<sup>` 标签来格式化此类脚注编号，或者最好使用 CSS 样式类来区分数字作为脚注而不是实际文本的一部分。如果您选择使用通用的 Boost 样式表，则为此目的定义了一个 `footnote` 类。
每个页面底部都应有一些修订信息，指示页面上次修改的时间。此信息应使用 `
<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 复制）
