哈囉！去年花了一些時間處理 Git man page之後，我又多想了一下，究竟怎樣的 man page 才算是好的 man page。

我花了很多時間為那些以 man page 作為主要說明文件的工具（像是 tcpdump、git、dig 等）編寫速查表。這是因為我常常覺得 man page 很難快速找到想要的資訊。

最近我一直在想——man page 本身能不能就內建一份超棒的速查表呢？怎樣的 man page 會更好用？我對這個想法的思考還在非常早期的階段，但想先把一些隨手筆記寫下來。

我在 Mastodon 上詢問了一些人，請他們分享最喜歡的 man page，以下是我在那些 man page 上看到的一些有趣做法。

OPTIONS SUMMARY（選項總覽）

如果你讀過很多 man page，應該會在 SYNOPSIS 裡看過類似這樣的內容：一旦列出幾乎整個字母表，就很難閱讀

ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]

grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]

rsync man page 有一個我從未見過的解法：它把 SYNOPSIS 寫得非常精簡，像這樣：

 Local:
     rsync [OPTION...] SRC... [DEST]

然後它有一個「OPTIONS SUMMARY」區段，用一行來總結每個選項，像這樣：

--verbose, -v            increase verbosity
--info=FLAGS             fine-grained informational verbosity
--debug=FLAGS            fine-grained debug verbosity
--stderr=e|a|c           change stderr output mode (default: errors)
--quiet, -q              suppress non-error messages
--no-motd                suppress daemon-mode MOTD

接著後面才是有每個選項完整說明的一般 OPTIONS 區段。

依類別組織的 OPTIONS 區段

strace man page 是依類別（像是「General」、「Startup」、「Tracing」與「Filtering」、「Output Format」）而非依字母順序來組織選項。

作為實驗，我試著把 grep man page 改成一個依類別分組的「OPTIONS SUMMARY」區段，你可以在這裡看到成果。我還不太確定自己怎麼看待這個結果，但這是個有趣的練習。寫的時候，我一直在想自己怎麼老是記不住 grep 的 -l 選項名稱。在 man page 裡找到它，感覺總是要花好久，我一直在思考怎樣的結構能讓我更容易找到它。也許用分類會比較好？

速查表

有幾個人向我推薦了整套 Perl man page（perlfunc、perlre 等），我注意到其中有 man perlcheat，它有像這樣的速查表區段：

 SYNTAX
 foreach (LIST) { }     for (a;b;c) { }
 while   (e) { }        until (e)   { }
 if      (e) { } elsif (e) { } else { }
 unless  (e) { } elsif (e) { } else { }
 given   (e) { when (e) {} default {} }

我覺得這超酷，也讓我開始好奇，是否還有其他方式可以用 80 字元寬的純文字 ASCII 速查表形式，寫出適合放在 man page 裡的精簡內容。

範例非常受歡迎

一個常見的回饋大概是「我喜歡任何有範例的 man page」。有人提到 OpenBSD 的 man page，而 OpenBSD 的 tail man page 最後就包含了我平常使用 tail 的那兩種用法的範例。

我印象中 EXAMPLES 區段最常出現在 man page 的最後，不過有些 man page（像前面提到的 rsync man page）會把範例放在最前面。當我處理 git-add 和 git rebase 的 man page 時，我在開頭放了一個簡短的範例。

目錄與區段間的連結

這並不是 man page 本身的特性，但在終端機裡閱讀 man page 時，有一個問題是很難知道整份 man page 有哪些區段。

在處理 Git man page 時，我和 Marie（瑪莉）做的一件事，就是在 Git 網站上託管的 man page 的 HTML 版本側邊欄加上目錄。

我也希望之後能在 Git man page 的 HTML 版本中加入更多超連結，這樣就可以點選「INCOMPATIBLE OPTIONS」直接跳到該區段。因為 Git 的 man page 是用 AsciiDoc 產生的，要加上這類連結非常容易。

我覺得加上目錄和內部超連結算是個不錯的折衷方案，至少能在 HTML 版本的 man page 上對 man page 格式做一些改進，而不需要另外維護一種完全不同的說明文件形式。不過要做到這點，確實需要像 Git 的 AsciiDoc 系統那樣建立一套工具鏈。

如果能有一種通用的系統，讓人輕鬆在 man page 裡查詢特定選項（像是「-a 是做什麼的？」）就太棒了。我所知道最好的技巧是用 man 的分頁器去搜尋類似 ^ *-a 的模式，但我總是記不得要用這招，結果還是得在 man page 裡逐一查看每個 -a，直到找到想要的說明為止。

每個選項的範例

curl man page 為每個選項都提供了範例，而且 HTML 版本上也有目錄，讓你更容易跳到感興趣的選項。

例如 --cert 的範例讓人很容易看出，你可能還會想同時帶上 --key 選項，像這樣：

  curl --cert certfile --key keyfile https://example.com

他們的做法是為每個選項各建立一個檔案（https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md），而該檔案裡有一個「Example」欄位。

用表格呈現資料

不少人說 man ascii 是他們最喜歡的 man page，它的樣子像這樣：

 Oct   Dec   Hex   Char                     
 ───────────────────────────────────────────
 000   0     00    NUL '\0' (null character)
 001   1     01    SOH (start of heading)   
 002   2     02    STX (start of text)      
 003   3     03    ETX (end of text)        
 004   4     04    EOT (end of transmission)
 005   5     05    ENQ (enquiry)            
 006   6     06    ACK (acknowledge)        
 007   7     07    BEL '\a' (bell)          
 010   8     08    BS  '\b' (backspace)     
 011   9     09    HT  '\t' (horizontal tab)
 012   10    0A    LF  '\n' (new line)      

顯然 man ascii 是個比較特別的 man page，但我覺得這個 man page 厲害的地方（除了它本身就是一份隨時可用的 ASCII 對照表之外）就在於，透過表格格式，讓人很容易掃視並找到需要的資訊。這也讓我好奇，是否還有更多機會在 man page 裡用「表格」來呈現資訊，讓內容更容易掃讀。

GNU 的做法

當我談到 man page 時，常常會有人提到 GNU coreutils 的 man page（例如 man tail）沒有範例，不像有提供範例的 OpenBSD man page（可參考此處）。

我不會在這裡深入討論這個議題，因為這似乎是個相當具政治性的話題，而且我在這裡肯定無法講得周全，不過以下有幾點我認為是事實：

• GNU 專案偏好以「info」說明文件而非 man page 來維護說明文件。這個頁面提到「man page 已不再維護」。
• 有 3 種方式可以閱讀「info」說明文件：透過其 HTML 版本、在 Emacs 中，或使用獨立的 info 工具。我聽過一些 Emacs 使用者說他們喜歡 Emacs 的 info 瀏覽器。我想我從未和任何會使用獨立 info 工具的人聊過。
• tail 的 info 說明文件條目有在 man page 底部提供連結，而且裡面確實有範例
• FSF 過去曾販售 GNU 軟體手冊的紙本書（而且也許現在偶爾仍有販售？）

當 man page 複雜到一定程度後，就會變得非常難以瀏覽：雖然我從未使用過 coreutils 的 info 說明文件，之後大概也不會用，但比起透過 man page，我幾乎肯定會更想透過 HTML 說明文件來使用 GNU Bash 參考手冊或The GNU C Library Reference Manual。

一些與 man page 相關的有趣工具

以下是一些我覺得很有趣的工具：

• The fish shell 內建了一個 Python 腳本，可以從 man page 自動產生 tab 補全
• tldr.sh 是一個由社群維護的範例資料庫，例如你可以執行 tldr grep。很多人告訴我他們覺得它很有用。
• Dash 這款 Mac 說明文件瀏覽器內建了不錯的 man page 檢視器。我仍然使用終端機裡的 man page 檢視器，但我喜歡它有包含目錄，介面看起來像這樣：

思考受限格式的有趣之處

Man page 是非常受限的格式，而思考在如此有限的排版選項下還能做些什麼，是件很有趣的事。

即使我非常喜歡寫作，我一直有個壞習慣，就是從來不看說明文件，所以其實很難去思考我在 man page 中到底覺得什麼才是有用的，我不太確定這篇文章裡提到的多數做法是否真的會改善我的使用體驗。（除了範例，我超愛範例）

所以我很想聽聽大家覺得哪些設計良好的 man page 值得推薦，以及你們喜歡它們的哪些地方，留言區在這裡。