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

我花了很多時間為那些以 man page 作為主要文件的工具（像是 tcpdump、git、dig 等）撰寫 cheat sheet。這是因為我常常覺得 man page 很難導覽，很難找到自己想要的資訊。

最近我在想——有沒有可能 man page 本身就內建一份很棒的 cheat sheet 呢？要怎麼樣才能讓 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」區塊，你可以在這裡看到成果。我不太確定怎麼評價這個結果，但算是個有趣的練習。寫的時候我在想，我老是記不住 -l 這個 grep 選項的名字，每次在 man page 裡找都要找超久，所以一直在想怎樣的結構會讓我比較好找。或許用分類會有幫助？

一份 cheat sheet

有幾個人推薦我去看 Perl 的一系列 man page（perlfunc、perlre 等），我注意到其中有一個 man perlcheat，裡面有像這樣的 cheat sheet 區塊：

 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 cheat sheet 放進 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 官網上託管的 HTML 版 man page 側邊欄加上目錄。

我也希望之後能在 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。這個頁面上說「the man pages are no longer being maintained」。
• 閱讀「info」手冊有三種方式：看它的 HTML 版本、在 Emacs 裡看，或是用獨立的 info 工具。我聽過一些 Emacs 使用者說他們喜歡 Emacs 裡的 info 瀏覽器，但我好像從沒跟任何有用過獨立 info 工具的人聊過。
• Man page 底部有連結到 tail 的 info 手冊條目，那裡面是有範例的
• FSF 以前會販售 GNU 軟體手冊的紙本書（而且或許現在偶爾還在賣？）

當複雜度到一定程度後，man page 就會變得非常難導覽：雖然我從沒用過 coreutils 的 info 手冊，大概以後也不會用，但我幾乎可以肯定會更想透過 HTML 文件去看 GNU Bash 參考手冊或The GNU C Library Reference Manual，而不是透過 man page。

一些與 man page 相關的東西

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

• fish shell 附帶一個 Python 腳本，可以從 man page 自動產生 tab 補齊
• tldr.sh 是一個由社群維護的範例資料庫，例如你可以執行 tldr grep 來使用。很多人跟我說他們覺得它很有用。
• Dash 這個 Mac 文件瀏覽器裡有一個不錯的 man page 檢視器。我還是習慣用終端機的 man page 檢視器，但我喜歡它有附目錄，看起來像這樣：

思考受限的格式很有趣

Man page 是格式非常受限的一種形式，能思考在這麼有限的排版選項下還能做些什麼，滿有趣的。

雖然我很喜歡寫作，但我一直有個壞習慣就是從不看文件，所以要我去想 man page 裡到底什麼對我有用，其實有點困難，我也不確定這篇文章裡提到的大多數東西是不是真的會改善我的使用體驗。（除了範例外，我超愛範例）

所以我很想聽聽你覺得哪些 man page 設計得很好、喜歡它們的哪些地方，留言區在這裡。