こんにちは！先月のman ページについての考察で得た一番の気づきは、man ページの用例は本当に素晴らしいということでした。そこで、お気に入りのツールを2つ選んで、その man ページに用例を追加（あるいは改善）してみました。

こちらです：

• dig の man ページ（用例を追加しました）
• tcpdump の man ページの用例（こちらは既存の用例をアップデートしました）

目標：もっとも基本的な用例を載せる

ここでの目標は、本当に一番基本的な使い方の例を示すことでした。tcpdump や dig をたまにしか使わない人（あるいは一度も使ったことがない人！）に向けて、使い方を思い出せるようにするためです。

今のところ、「初心者やたまにしか使わない人向けに用例セクションを書きたいんです」と伝えるやり方がとてもうまくいっています。説明しやすいですし、man ページに何を求めているかについてユーザーから聞いたこととも合致していると思いますし、メンテナーの方々にも納得してもらえているようです。

ドキュメントの変更をレビューしてくれた Denis Ovsienko さん、Guy Harris さん、Ondřej Surý さん、そして他のすべての方々に感謝します。良い経験になり、man ページにもう少し手を入れていこうという意欲が湧きました。

なぜ man ページを改善するのか？

今、ツールの公式ドキュメントに取り組みたいと思っている理由は次のとおりです：

• man ページは、ほぼ 100% 正確な情報を載せることができるんです！情報が本当に正しいかどうかを確認するレビュープロセスを経ることには大きな価値があります。
• 「もっともよく使われる tcpdump のフラグは何か」といった基本的なことでさえ、メンテナーの方は私の知らない便利な機能を把握していることが多いんです！たとえば今回 tcpdump の用例に取り組む中で、tcpdump -w out.pcap でパケットをファイルに保存する際に -v を付けると、これまでに何パケットキャプチャしたかのライブサマリーが表示されるということを学びました。これは本当に便利で、知らなかったことですし、自分だけでは決して気づかなかったと思います。

正直なところ、私はいつもドキュメントは読みにくいものだと決めつけて、たいていは飛ばしてブログ記事や Stack Overflow のコメントを読んだり、友人に聞いたりしているので、今の自分の立ち位置はちょっと不思議な感じがします。でも今は楽観的な気分です。もしかしたらドキュメントは悪くなんてなくてもいいのかもしれない？すごく良いブログ記事を読むのと同じくらい良いものになりうるけれど、さらに実際に正確だという利点も付いてくる、みたいな。最近 Django のドキュメントを使っているのですが、本当に素晴らしいです！今後に期待です。

man ページの言語を書かずに済ませる工夫

tcpdump プロジェクトの man ページはroff 言語で書かれており、ちょっと扱いづらく、正直学びたいとは思えませんでした。

そこで、とてもシンプルな Markdown から roff への変換スクリプトを書いて、man ページがすでに使っていたのと似た規約で Markdown を roff に変換することで対応しました。pandoc を使ってもよかったのかもしれませんが、pandoc の出力はかなり違うように見えたので、自分でスクリプトを書いた方がいいだろうと思ったのです。どうなんでしょうね。

既存の Markdown ライブラリの Markdown AST をパースする機能を使って、あとはこの文脈で理にかなっていると思える形でフォーマットするためのコード出力メソッドを自分で実装する、というやり方ができたのは面白かったです。

man ページは複雑

BSD システム（そしていくつかの Linux システム、そしてたぶん macOS）が man ページのフォーマットに使っているmandoc プロジェクトについて知ったことをきっかけに、roff の歴史や、70 年代からどのように進化してきたのか、そして今誰が取り組んでいるのかについて、すっかり沼にハマって調べました。ただ、今日はこれ以上は語りません。また別の機会に。

全般的に、BSD と Linux でドキュメントがどのように扱われているかには、技術的にも文化的にも隔たりがあるように思えますが、まだよく理解できていません。ただ、BSD の世界で何が起きているのか、気になっています。

コメント欄はこちらです。