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.dev.org.tw/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.dev.org.tw/LICENSE_1_0.txt 的副本)
