こんにちは！先月の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に変換するとてもシンプルなmarkdown-to-roffスクリプトを書き、manページがすでに使っていた流儀に合わせて変換するようにしました。pandocを使ってもよかったかもしれませんが、pandocが出力する結果はかなり違って見えたので、自分でスクリプトを書いた方がよいだろうと考えました。どうなのかは分かりませんが。

既存のMarkdownライブラリのMarkdown ASTを解析する機能を使って、自分でコードを出力するメソッドを実装し、この文脈に合った形でフォーマットできたのは面白かったです。

manページは複雑です

BSD系のシステム（そして一部のLinuxや、たぶんmacOSも）がmanページのフォーマットに使っているmandocプロジェクトについて知ったことをきっかけに、roffの歴史や70年代からの変遷、そして今誰が開発しているのかをとことん調べてしまいました。今日はこれ以上触れませんが、また別の機会にしたいと思います。

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

コメントはこちらです。