哈囉！上個月我對 man page 的一些想法中，最大的收穫就是 man page 裡的範例真的非常棒，所以我幫我最喜歡的兩個工具的 man page 新增（或改進）了範例。

就在這裡：

• dig 的 man page（現在有範例了）
• tcpdump 的 man page 範例（這是對先前範例的更新）

目標：加入最基礎的範例

這裡的目標其實就只是提供最最基礎的工具使用範例，給那些不常使用 tcpdump 或 dig（或是從來沒用過！）而已經不記得怎麼用的人。

到目前為止，說「嘿，我想為初學者和不常使用的使用者寫一個範例章節」這個說法效果一直很好。很好解釋，而且就我從使用者那裡聽到他們對 man page 的期待來說，我覺得很合理，維護者們似乎也覺得很有說服力。

感謝 Denis Ovsienko、Guy Harris、Ondřej Surý 以及其他所有審閱文件修改的人，這是一次很棒的經驗，也讓我更有動力繼續在 man page 上多做一點事。

為什麼要改進 man page？

我現在會想投入工具的官方文件，是因為：

• Man page 其實可以做到接近 100% 正確的資訊！透過審查流程來確保資訊確實無誤，價值非常高。
• 即使是「最常用的 tcpdump 參數有哪些」這種基本問題，維護者們也常常知道一些我不知道的好用功能！舉例來說，我在整理這些 tcpdump 範例時才學到，如果你用 tcpdump -w out.pcap 把封包存到檔案裡，加上 -v 會即時印出目前已經擷取了多少封包的摘要。這真的很實用，我之前完全不知道，而且我想我自己大概永遠也不會注意到。

對我來說這有點微妙，因為老實說我總是預設文件會很難讀，通常都會直接跳過，改去看部落格文章、Stack Overflow 的留言或問朋友。但現在我感到有點樂觀，也許文件不一定非得難讀不可？也許它可以跟一篇很棒的部落格文章一樣好讀，但好處是內容還是真正正確的？我最近一直在用 Django 的文件，真的寫得很好！再看看吧。

關於避開直接撰寫 man page 語言

tcpdump 專案的 man page 是用 roff 語言寫的，這種語言有點難用，而且我真的不太想學。

我的解法是寫了一個非常陽春的 markdown 轉 roff 腳本，把 Markdown 轉成 roff，用的也是跟原本 man page 類似的格式慣例。我本來也可以直接用 pandoc，但 pandoc 產生的結果看起來差蠻多的，所以我想或許自己寫一個腳本會比較好。誰知道呢。

我覺得蠻酷的是，可以直接利用現有 Markdown 函式庫解析 Markdown AST 的能力，然後自己實作產生程式碼的方法，用在這個情境下看起來合理的方式來排版。

man page 很複雜

我一頭栽進去研究 roff 的歷史、它從 70 年代以來如何演變，以及現在是誰在維護，這是受到 mandoc 專案的啟發——BSD 系統（還有一些 Linux 系統，我想 Mac OS 也是）就是用它來排版 man page 的。不過今天就不多說這個了，也許下次再談。

整體來說，BSD 和 Linux 在文件運作方式上似乎存在技術與文化上的分歧，我到現在還不是很懂，但我一直對 BSD 世界裡發生的事感到好奇。

留言區在這裡。