在手冊頁中記錄可變長度選項的正確方法

在手冊頁中記錄可變長度選項的正確方法

有時我會看到類似的使用訊息

some_utility [arg [arg [...]]]

或者

some_utility [arg[, arg[...]]]

這表示您可以傳遞多個相同的參數。

我也看過類似的

some_utility [args]

或者

some_utility [arg][, arg][...]

有沒有標準的方法來做到這一點?

答案1

不,不是真的,但大多數時候它是相當一致的。大多數手冊會列出帶方括號 ( ) 的可選參數[foo],帶有尖括號的強制參數或根本不帶括號(<bar>, baz,後一個通常帶有下劃線)。

另外,在幾乎所有情況下,如果參數的數量是可變的,您將擁有某種清單(如您所提到的,[quux ...][quux[, quux[...]]]...),其中類似地[quuz]大多數情況下都準確地表示爭論。在極少數情況下,[quuz]也可能意味著“一個或多個參數”,但大多數手冊都遵循列表形式的省略號。

這是一個準標準,但你不能絕對依賴它。但根據我的經驗,95%的情況下都是沒問題的。

關鍵是,有數百家各種顏色的軟體供應商,不僅有“大玩家”,而且還有由個人編寫的被證明有用的軟體。他們所有人(希望)以某種個人的方式編寫他們的線上幫助頁面......他們中的大多數人都知道足夠長的時間來處理常見的約定,但也有一些人不關心風格品味等或有某種精神缺陷; )

相關內容