tcpdump 與 dig 線上手冊範例
哈囉！我上個月關於線上手冊的隨想中最大的收穫，就是線上手冊裡的範例真的非常棒，所以我著手為我最喜愛的兩個工具的線上手冊新增（或改進）範例。
就是這些：
- dig 線上手冊（現已加入範例）
- tcpdump 線上手冊範例（這是對先前範例的更新）
目標：收錄最基礎的範例
這裡的目標其實很單純，就是提供工具最最基礎的使用範例，給那些不常使用 tcpdump 或 dig（或從來沒用過！）而記不起用法的人。
到目前為止，說「嗨，我想為這個工具的初學者和不常用使用者寫一個範例章節」這個說法效果一直很好。很好解釋，我覺得從使用者對於線上手冊的期待回饋來看也很有道理，而維護者們似乎也覺得這個想法很有吸引力。
感謝 Denis Ovsienko（丹尼斯・奧夫西延科）、Guy Harris（蓋伊・哈里斯）、Ondřej Surý（翁德熱・蘇利）以及所有審閱文件修改的人，這是一次很棒的經驗，也讓我更有動力繼續在線上手冊上多做一點事。
為什麼要改進線上手冊？
我現在會想投入工具的官方文件，是因為：
- 線上手冊其實可以做到接近 100% 正確的資訊！透過審閱流程來確保資訊確實無誤，本身就很有價值。
- 即使是「最常用的 tcpdump 旗標有哪些」這類基本問題，維護者往往也知道一些我不知道的實用功能！舉例來說，我在撰寫這些 tcpdump 範例時學到，如果你用
tcpdump -w out.pcap把封包存到檔案，搭配-v會很有用，它會即時印出目前已擷取了多少封包的摘要。這真的很實用，我以前不知道，而且我覺得靠自己大概永遠也不會注意到。
對我來說，這有點微妙，因為老實說我總是預設文件會很難讀，所以通常會直接跳過，改去看部落格文章或 Stack Overflow 留言，或是問朋友。但現在我感到比較樂觀，覺得也許文件不一定非得寫得很糟？也許它可以像一篇很棒的部落格文章一樣好讀，同時還附帶真正正確的好處？我最近一直在用 Django 的文件，寫得真的很好！就再看看吧。
關於避免直接撰寫線上手冊語言
tcpdump 這個專案工具的線上手冊是用 roff 語言撰寫的，這種語言有點難用，而我真的不太想去學它。
我的處理方式是寫了一個非常陽春的 markdown-to-roff 轉換腳本來把 Markdown 轉成 roff，採用與現有線上手冊類似的慣例。我本來或許可以直接用 pandoc，但 pandoc 產生的輸出看起來差異頗大，所以我想還是自己寫一個腳本比較好吧。誰知道呢。
我確實覺得能夠直接利用現有 Markdown 函式庫解析 Markdown AST(抽象語法樹) 的能力，然後自己實作產生程式碼的方法，以在這個情境下用合理的方式來格式化內容，還滿酷的。
線上手冊很複雜
我一頭栽進去研究 roff 的歷史、它自 70 年代以來的演變，以及如今是誰在維護它，起因是了解到 mandoc 這個專案——BSD 系統（以及一些 Linux 系統，還有我認為的 Mac OS）用來排版線上手冊的工具。今天就不多談這個了，或許下次再說。
整體而言，BSD 和 Linux 在文件運作方式上似乎存在技術與文化上的分歧，我還沒有真正搞懂，但一直很好奇 BSD 世界裡究竟發生了什麼事。