CLI 工具說明相關規定

總覽

與透過 --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.

一般版面配置和樣式

請參閱上述規範的範例。

因此有幾個部分需要撰寫英文課文。這代表寫作 句子使用英文文法，搭配美國英文拼字 (相對於英國) 英文或其他語言)。句子之間應以一個空格分隔，並遵循「牛津」的 逗號"。例如：「說明、範例和附註」皆以英文撰寫 CANNOT TRANSLATE

版面配置

  • 每個部分由一行空白行分隔。
  • 區段內容會以兩個空格縮排。
  • 單行內容會和具有一個標籤的同一行寫入 分隔冒號和指令名稱的空格。例如：「Usage: blast <file>」。
  • 系統會緊接在標籤之後撰寫多行區段 (沒有 空白行)。標籤後方的每一行都會縮排兩個空格。
  • 所有輸出內容都是單一資料欄，但「選項」、「指令」、 以及錯誤代碼，分別是兩欄表格。
  • 使用空格進行縮排或對齊。不要輸出定位字元。
  • 在 80 欄文字環繞文字。包裝選項或指令說明時，對齊 後續這行程式碼也包含在說明開頭 (例如約 20 字元)。

樣式

  • 區段標題採用首字母大寫：將開頭和最後一個字詞大寫。所有語言 除了文章 (a、a、the)、 連接詞 (例如，及、、) 和介系詞 (例如 on、in、with)。
  • 從簡短說明片段 (「選項」或「指令」的第二欄) 開始出現 且並非完整的句子。任何文字 除簡短說明外，應包含完整的句子， 片段。
  • 試著讓每個部分保持精簡。如有其他意見，請引導使用者前往 在執行 --help 時使用 --verbose，或引導他們前往完整的 說明文件。
  • 描述性文字 (玫瑰) 可使用 Unicode (UTF-8) 字元。 指令名稱和使用文字只會包含可攜式 ASCII 字元 (不含 Unicode)。

用量

必須使用且包含「Usage:」標題。

Usage: blast [-f] [-s <scribble>] <command> [<args>]

用量通常為單行，但多行可用於 釐清哪些選項可以互斥。如果所需的行數 表示所有互斥的情況會變得過多， 並在完整的文件中提供更多詳細資料。如果有許多 可以互斥的選項，請考慮建立子指令或使用其他工具 降低作業複雜度

使用語法

指令名稱會先列出。指令名稱沒有硬式編碼： 由指令名稱動態提取，也就是 argv[0] 上的最後一個元素 路徑。因此，單一二進位檔可以做為多種不同的工具運作。

名稱和使用文字只會包含可攜式 ASCII 字元。全部長 形式指令必須完全小寫，也就是一律不採用全部大寫或混合大小寫。單身 字母切換應優先使用小寫，但可以使用大寫。

使用有意義的字詞做為選項和預留位置。避免使用縮寫。偏好 單一字詞如果使用多個字詞，請以連字號分隔字詞 (-)，不要使用底線、駝峰式大小寫或字詞組合。

除了指令名稱之外，還有幾種引數 (如 一文。

  • 完全相符的文字
  • 引數
  • 選項 (開關和按鍵)
  • 按鍵選項
  • 選項分隔符號
確切文字語法

實際文字在使用行中會照原樣寫成。在此範例中，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」如果習慣分隔選項 也就是「或」

例如：

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>...]」也就是說 「Usage: copy [<from>...] <to>」則為 <from> 個項目等於 0 或多個 已接受 <from> 個項目。

至於可重複執行的鍵/值組合，請用方括號將其分組 (如果配對成功) ) 或括號 (非選填)，並加上刪節號 群組 (例如[--input <file>]... 或 (--input <file>)...。

括號

角括號 (<>)、方括號 ([]) 和括號 (()) 不會 加入空格

[from] # correct
<to> # correct
(-a|-b) # correct

[ from ] # incorrect
< to > # incorrect
( -a|-b ) # incorrect

角括號 (<>) 會換行或鍵/值，

括號 ([]) 會包裝選用元素。使用巢狀角括號，例如 [<file>]，將 <file> 解讀為可選的引數。巢狀 「[<」不是獨立的括號樣式，而是「[」帶有「<」在其中建立目錄 建立巢狀結構時，括號 ([) 會位於最外層 (請勿使用 <[file]>)。

括號 (()) 可用來將元素分組。使用括號表示有助於改善成效 例如提供可互斥的選項

括號 ({}) 會保留供日後使用。本指南會刻意保持開放狀態 這樣的話，在日後修訂 文件。

說明

說明為必填資訊，且不含標題。例如：說明 區域未加上「說明」標籤例如：

Destroy the contents of <file>.

說明內容以美國英文冗詞撰寫 (完整的句子，請使用 US 編碼)。 英文文法、拼字和標點符號)。

每項工具應該都會說明其功能，而本節也將說明實際用途。

「說明」部分應會描述

  • 工具的功能 (必填)
  • 使用的平台設定
  • 配置、資料格式或使用的通訊協定
  • 黃金工作流程 (重要的開發人員歷程)
  • 廣泛的說明文件網址 (例如 fuchsia.com/docs 或類似檔案，請避免提供 連結。

「說明」部分也可以包含「另請參閱」是指其他工具 依據名稱 (避免使用網址)。

說明中不得填入的內容

  • 使用的環境變數，但不包括已在「選項」中列出的變數 (請在「選項」或「附註」中提供這項資訊)
  • 安全性危害 (請在「附註」部分說明)
  • 錯誤代碼 (請填入「錯誤代碼」部分)
  • 著作權 (請勿在 --help 中加入此內容)
  • 作者 (請不要加入 --help 中)
  • 如何取得子指令的說明 (這項資訊位於 help 子指令)
  • 如何更新工具 (應該在工具說明文件中 套件 (如適用)
  • 版本資訊 (使用個別檔案)

選項

如果程式接受引數，就必須提供「選項」部分。例如：

Options:
  -f              force, ignore minor errors
  -s <scribble>   write <scribble> repeatedly. Defaults to $BLAST_SCRIBBLE.

列出的選項適用於工具本身，而非子指令。選項 要求取得該子指令協助時，就會列出個別子指令。例如， 搭配 blast help grind 或 blast grind --help 使用時

請盡量將選項保持在一個完整的字詞。如果需要兩個字詞 請以連字號 (-) 分隔字詞。避免使用不常見的縮寫。

依字母順序顯示選項清單。

指令選項會分行列出每個引數、切換鈕和按鍵選項，且各行 但簡短和長版引數的引數除外。如果引數 分別出現在同一行、簡短形式 ，並以 , (逗號空格) 分隔，例如：-f, --force。

「選項」部分就不會列出確切的文字引數。會顯示 「用量」部分

依原樣輸入的文字不會用括號包住，而變數項目 會以角括號 (<>) 顯示，選用項目則以方括號括住 ([])。列出選項時，金鑰絕並非可選項目。例如：

  -a                   a good example
  [-b]                 a bad example, to use -b it must be typed as-is

每個選項後方會顯示簡短說明。 但要簡單扼要試著在整體工具中提供更多詳細資料 說明、範例或附註，而不會建立冗長的選項 生成 3D 物件

說明內容

  • 簡單提醒一下該選項所代表的意義，例如：ignore minor errors
  • 當選項覆寫其他選項 (例如-x implies -c and -p
  • 預設值，例如defaults to $BLAST_SCRIBBLE

說明語句片段開始的資料欄可能因情況而異 確實會改善工具的需求如果看起來沒問題，請使用從左側邊緣算起 20 個字元 但可調整閱讀頻率

如果選項數量很多，建議您顯示實用的子集 說明如何取得上述所有功能的進一步協助，例如傳送 「--verbose」，以及「--help」。

指令

如果程式有子指令，就必須設定指令區段。如果有的話 為「指令：」例如：

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

每個範例都含有美式英文節音 (即完整句子，請使用 US 編碼)。 英文文法、拼字和標點符號) 可用來說明範例，後面接著 範例指令列請在指令列中輸入的每一行 開頭會加上「$」模仿命令提示字元

如要包裝過長的範例，請在前一行結尾加上「\」和 之後一行以「」為開頭(空格) 表示行連續。

  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:
  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 文件)。
  • 殼層專屬說明 (例如如何將輸出內容或管道重新導向至分頁器)。