總覽
指令列說明 (通常透過 --help 提供)，是與使用者溝通的重要方式。其中提供了更詳細的說明文件和功能探索。
指南
說明文件可能包含下列部分 (如有需要)：
範例
本文件的後續章節會詳細說明。(請注意，blast 並非實際工具)。
Usage: blast [-f] [-s <scribble>] <command> [<args>]
Destroy the contents of <file>.
Options:
-f force, ignore minor errors. This description
is so long that it wraps to the next line.
-s <scribble> write <scribble> repeatedly
-v, --verbose say more. Defaults to $BLAST_VERBOSE.
Commands:
blow-up explosively separate
grind make smaller by many small cuts
help get help on other commands e.g. `blast help grind`
Examples:
Scribble 'abc' and then run |grind|.
$ blast -s 'abc' grind old.txt taxes.cp
Notes:
Use `blast help <command>` for details on [<args>] for a subcommand.
Error codes:
2 The blade is too dull.
3 Out of fuel.
一般版面配置和樣式
請參閱上方範例，瞭解如何遵守這些規定。
而數個部分的路段是以英文繁體稱呼。也就是說，使用英文文法 (而非英式英文或其他) 字時，請使用英文文法撰寫正確的句子。語句之間應使用一個空格，並遵循「牛津逗號」樣式。例如：「The Description、Sample 和 Notes 區段是以英文漸進撰寫」。
版面配置
- 每個部分會以空白行分隔。
- 區段內容已縮排兩個空格。
- 系統將在與標籤相同的行中編寫單行內容，並以一個空格分隔冒號和指令名稱。例如「
Usage: blast <file>」。 - 多行區段將會立即寫在標籤後方 (無空白行)。標籤後方的每一行都會縮排兩個空格。
- 所有輸出內容都是單一資料欄，但「選項」、「指令」和「錯誤代碼」這類欄位分為兩個資料欄資料表。
- 使用空格來縮排或對齊。不要輸出定位字元。
- 將文字環繞 80 欄。包裝選項或指令說明時，請將後續幾行對齊說明的開頭 (例如約 20 個半形字元)。
樣式
- 區段標題以首字母大寫表示：首字和最後一個字詞大寫。兩者之間的所有字詞也都會大寫，但除了文章 (a、a、the)、組合詞 (例如與、但、或者) 和介係詞 (例如 on、in、in) 之外。
- 簡短說明片段 (「選項」或「指令」中的第二欄) 以小寫英文字母開頭，因此不應是完整的句子。簡短說明之外的所有文字都必須是完整的句子，且片段後面必須加上句號。
- 請盡量讓每個部分保持精簡。如果更多意見，請引導使用者在執行
--help時使用--verbose，或引導他們查看完整說明文件。 - 說明文字可使用 Unicode (UTF-8) 字元。指令名稱和使用文字僅包含可攜的 ASCII 字元 (不含萬國碼)。
使用方法
必須使用且包含「Usage:」標頭。
Usage: blast [-f] [-s <scribble>] <command> [<args>]
用量通常為單行，但當選項彼此互斥時，可以使用多行來釐清情況。如果呈現所有互斥情況所需的行數過多，請將行數限制在一些常見情況，並在完整文件中提供詳細資料。如果您有多個互斥的選項，請考慮建立子指令或使用不同的工具，以降低複雜程度。
使用語法
系統會優先列出指令名稱。指令名稱並非採用硬式編碼，系統會從指令名稱動態提取，也就是 argv[0] 路徑中的最後一個元素。如此一來，單一二進位檔就能做為多項不同的工具運作。
名稱和使用文字只會包含可攜的 ASCII 字元。所有長格式指令都是完全小寫，即一律不全部大寫或混合使用大小寫。單一字母切換應偏好小寫，但允許使用大寫。
為選項和預留位置使用有意義的字詞。避免使用縮寫。最好使用單一字詞。使用多個字詞時，請以連字號 (-) 分隔字詞，即請勿使用底線、駝峰式大小寫或一起執行多個字詞。
除了指令名稱之外，還有幾種不同類型的引數 (如Fuchsia 工具相關規定所述)。
- 完全相符的文字
- 引數
- 選項 (切換鈕和按鍵)
- 索引鍵選項
- 選項分隔符號
完全相符的文字語法
精確的文字會依原樣寫成使用行中。在「Usage: copy
<from> to <destination>」範例中，to 字詞是確切的文字。如果文字為選用項目，則會以方括號 ([]) 括住，並出現在用法行中：「Usage:
copy <from> [to] <destination>」。
引數語法
引數會以角括號 (<>) 包住，以便與煽情露骨內容有所區別。在 Usage: copy <from> <destination> 範例中，<from> 和 <destination> 都是引數。如果引數不是必要引數，則會以方括號 ([]) 括住，例如：Usage: copy <from> [<destination>]。另請參閱選項分隔符號。
選項語法互斥
表示相互獨立的選項時，有幾個選項可以選擇。
如果提供多個用量行，每個行都會顯示一組互斥的指令。例如：
Usage:
swizzle [-z] <file>
swizzle --reset
表示 --reset 和搭配 <file> 的使用是互斥的選項。
另一個指定互斥選項的方法是在選項之間使用垂直線 (「|」)。請注意，使用垂直長條表示資料在不同程序之間的流動情形，就稱為「Pipe」。用來分隔選項時，會讀成「Or」。
例如：
Usage: froth [-y|-z] <file>
表示 -y 或 -z 開關可以 (或兩者都不選) 使用 (兩者並非必要)，但最好兩者並用 (兩者並用)。如要表示僅限使用任一值，但不得兩者並用，請用括號括住選項。例如，「Usage: froth (-a|-b) <file>」表示必須傳遞 -a「或」 -b。
請注意，--version 或 --help 常會導致其他引數遭到忽略，且不會顯示出來。建議您將這些程式碼列為獨立的用量行。
分組 (隱含) 選項
目前沒有特定的語法來表示啟用選項時也會影響其他選項。如果選項暗示其他選項已啟用或停用，請在「選項」中加以指定。例如，「passing -e implies -f」表示如果啟用 -e，-f 就會像在指令列上傳遞一樣啟用 (無論 -f 是否已明確傳遞)。多餘傳遞隱含值不會造成傷害 (並非錯誤)。
記錄主要切換按鈕的影響。例如，如果 -x implies -c and -p 在 -x 的說明中加入附註，而不是在 -c 和 -p 中。這是為了讓 --help 輸出內容保持精簡 (可在完整說明文件中放寬這項規則)。
選用鍵
如要以選用鍵為索引鍵選項建立外觀，請建立選用的完全比對文字，後面加上引數。例如「Usage: copy [from] <from> [to]
<destination>」。在這個例子中，這些都是有效的值：「copy a b」、「copy
from a b」、「copy from a to b」、「copy a to b」。
重複選項
如果相同的位置引數可能會重複，請使用刪節號 (...) 表示。請勿使用連續的萬國碼 (Unicode) 刪節號。例如：「Usage: copy <from> [<from>...] <to>」表示最後一個引數一律會解讀為 <to>，而上述值則為多個 <from> 項目。請注意，「<from> [<from>...]」表示至少有一個 <from> 項目，「Usage: copy [<from>...] <to>」則代表可接受零或多個 <from> 項目。
針對可能會重複的鍵/值組合，請用括號 (如果組合為選用) 或括號 (如果組合為選用) 分組，然後在群組中分別加上刪節號，例如 [--input <file>]... 或 (--input <file>)...。
括號
角括號 (<>)、方括號 ([]) 和括號 (()) 不會立即包含空格。
[from] # correct
<to> # correct
(-a|-b) # correct
[ from ] # incorrect
< to > # incorrect
( -a|-b ) # incorrect
角括號 (<>) 包裝引數或鍵值。
括號 ([]) 會納入選用元素。使用巢狀角括號 (例如 [<file>]) 時，您可以將 <file> 解讀為選用引數。巢狀「[<」不是獨立的括號樣式，而是包含「<」的「[」。建立巢狀結構時，括號 ([) 位於最外 (請勿使用 <[file]>)。
括號 (()) 可用來將元素分組。請使用括號提高明確性，例如需要的互斥選項。
括號 ({}) 保留供日後使用。本指南刻意讓括號在日後的修訂版本中具有特殊意義。
說明
必須提供說明，且不含標題。換句話說，說明區域不是標示為「description」例如：
Destroy the contents of <file>.
說明以美式英文繁體撰寫 (使用美式英文文法、拼字和標點符號的完整句子)。
每項工具都應該提供相關資訊，您可以在這個部分說明這項功能。
「說明」部分應描述
- 工具的用途 (必要)
- 所用的平台設定
- 使用的機制、資料格式或通訊協定
- 黃金工作流程 (開發人員的重要流程)
- 請提供說明文件，例如 fuchsia.com/docs 或類似網址，避免使用容易過時的深層連結
「說明」部分也可以包含「另請參閱」參照其他工具的名稱 (避免使用網址)。
「說明」部分不應加入的內容
- 使用的環境變數，不是「選項」中列出的變數 (請在「選項」或「附註」中提供此值)
- 危害安全風險 (請參閱「附註」一節的說明)
- 錯誤代碼 (請在「錯誤代碼」部分列出)
- 版權 (請勿在
--help中加入這項內容) - 作者 (請勿加入
--help) - 如何取得子指令的說明 (請將這個指令放在
help子指令的簡短說明) - 如何更新工具 (如適用) 工具套件的說明文件
- 版本資訊 (請使用獨立的檔案)
選項
如果程式接受引數，就必須使用「Options」區段。例如：
Options:
-f force, ignore minor errors
-s <scribble> write <scribble> repeatedly. Defaults to $BLAST_SCRIBBLE.
列出的選項會套用至工具本身，而非子指令。當您要求該子指令的說明時 (例如使用 blast help grind 或 blast grind --help)，系統會列出各個子指令的選項。
盡量讓選項保持在一個完整的字詞。如果需要兩個字詞，請以連字號 (-) 分隔字詞。請避免不常見的縮寫。
依字母順序呈現選項清單。
選項會以不同行列出每個引數、切換鈕和索引鍵選項，但含有短和長格式的引數除外。如果引數皆有短和長格式，請在同一行列出，並優先採用簡短格式，並以 , (半形空格) 分隔，例如 -f, --force。
正確的文字引數不會顯示在「選項」部分中。會顯示在「用量」區段中。
系統會將輸入時依原樣輸入的文字包在括號中，而變數項目會以角括號 (<>) 顯示，選用項目則會顯示在方括號 ([]) 中。列出選項時，Key 不得為選用。例如：
-a a good example
[-b] a bad example, to use -b it must be typed as-is
每個選項都會提供簡短說明。說明文字沒有長度限制，但簡潔扼要。嘗試在整體工具說明、範例或附註中加入更詳盡的資訊，而不要建立冗長的選項說明。
說明內容
- 簡單提醒該選項隱含的意義，例如：
ignore minor errors - 如果該選項會覆寫其他選項，例如
-x implies -c and -p - 預設值，例如
defaults to $BLAST_SCRIBBLE
說明句子片段開始所在的資料欄，可能會因工具的需求而不同。如果看起來沒問題，請使用左側邊緣 20 個字元，但如果讀數多或少，請進行調整。
如果選項數量很多，建議您顯示實用的子集，並說明如何進一步查看這些選項，例如搭配 --help 傳遞 --verbose。
指令
如果程式有子指令，就必須設定指令區段。如果存在標籤，會加上「Commands:」標籤。例如：
Commands:
blow-up explosively separate
grind make smaller by many small cuts
help get help on other commands e.g. `blast help grind`
如果程式沒有子指令，就不會顯示指令區段。
如果工具有子指令，它也會具備 help 指令，可提供子指令 (例如 blast help grind) 的進一步說明。
盡量讓子指令只包含一個完整的字詞。如果需要兩個字詞，請以連字號 (-) 分隔字詞。請避免不常見的縮寫。按字母順序呈現指令清單。
每個指令名稱中會出現一行簡短說明。如需較長的指令說明，使用者會特別要求取得該指令的說明。這段說明只是簡短提醒該指令，並協助使用者探索指令。
如果指令數量眾多，請考慮顯示實用的子集，並說明如何進一步查看 (例如透過傳遞 --verbose 與 --help)。
範例
範例區段為選用項目。如有的話，系統會加上「範例：」標籤。 例如：
Examples:
Scribble 'abc' and then run |grind|.
$ blast -s 'abc' grind old.txt taxes.cp
每個範例都會有包含美式英文繁體的功能 (即使用美式英文文法、拼字和標點符號的完整句子)，並在後面說明指令列範例。您在指令列中輸入的每一行都會在前面加上「$」，模擬命令提示字元。
如要包裝過長的範例，請在前一行以「\」結尾，並以「」(空格) 開頭，表示線繼續。
This example wraps onto multiple lines.
$ blast -s 2332 some/long/path/cats.o \
more/long/path/dogs.o more/long/path/bears.o \
more/long/path/deer.o
如果顯示範例指令中的某些輸出內容會有幫助，請在範例後立即寫入輸出內容。
請使用一行空白行分隔範例。
如果「範例」部分的內容過長，請將範例移到說明文件中。互動式說明範例僅供快速參考及搜尋，不是完整說明文件。
附註
附註是選填項目，開頭則是「Notes:」標頭。例如：
Notes:
Use `blast help <command>` for details on [<args>] for a subcommand.
附註以美式英文繁體撰寫 (也就是使用美式英文文法、拼字和標點符號的完整句子)。
記事內容
- 使用，而非「選項」中所列的環境變數 (針對預設值)
- 安全危害
- 協助使用者的提醒
不應加入記事的內容
- 錯誤代碼 (請在「錯誤代碼」部分列出)
- 版權 (請勿在
--help中加入這項內容) - 作者 (請勿加入
--help) - 如何取得子指令的說明 (請將這個指令放在
help子指令的簡短說明) - 如何更新工具 (如適用) 工具套件的說明文件
- 版本資訊 (請使用獨立的檔案)
錯誤代碼
如果產生 0 或 1 以外的代碼，就必須提供「錯誤代碼」部分。例如：
Error codes:
2 The blade is too dull.
3 Out of fuel.
如果只有 0 或 1 結果是由程式產生，這個部分就會省略。
錯誤代碼 0 一律視為「無錯誤」，錯誤代碼 1 一律為「一般錯誤」。兩者都不會記錄在 --help 輸出內容中。0 或 1 以外的所有錯誤代碼都必須記錄在工具產生的所有。
平台規格
某些平台 (例如 DOS) 使用不同的選項前置字元 (例如 /)，或者可能會允許不區分大小寫的切換鈕。無論平台為何，工具都會使用破折號前置字元 (-) 和區分大小寫選項。這表示一般情況下，工具的說明文件不必考量所用平台。
不應納入 --help 輸出內容的內容
請勿顯示具有等號 (=) 的鍵/值組合，例如 --scribble=abc。系統會使用空白字元做為分隔符號 (--scribble abc) 剖析鍵和值。如果說明中的等於值，可能會讓使用者感到困惑。
請勿實作翻頁元素 (例如 more 程式，會在每個畫面中的文字時暫停輸出)。
不包含
- 說明輸出結果中的版權 (在合法情況下須指明版權)。
- 版本資訊 (請在版本資訊中附上)。
- 完整說明文件 (請在 Markdown 文件中註明)。
- 版本資訊 (從
--version的輸出內容)。 - 結果代碼
0或1的說明文件 (放在 .md 文件中)。 - 介面專屬說明 (例如如何將輸出內容或管道重新導向至 Pager)。