こんにちは！先月のmanページについての考察から得た大きな気づきは、manページの例が本当に素晴らしいということでした。そこで、私のお気に入りのツール2つの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-to-roffスクリプトを書いてMarkdownをroffに変換し、manページがすでに使っているのと似た規則に従うようにしました。pandocを使うこともできたかもしれませんが、pandocが出力するものはかなり違っていたので、自分でスクリプトを書いた方が良いと思ったのです。どうなるかはわかりません。

既存のMarkdownライブラリのMarkdown ASTを解析する機能を活用し、この文脈で意味がありそうな形式にフォーマットするための独自のコード生成メソッドを実装できるのは、なかなか面白いことだと思いました。

manページは複雑

roffの歴史や、1970年代以降の進化、そして今日誰が取り組んでいるのかについて、mandocプロジェクトについて学んだことをきっかけに、深く掘り下げて学びました。BSDシステム（および一部のLinuxシステム、Mac OSも含む）でmanページのフォーマットに使われているプロジェクトです。今日はこれ以上触れませんが、また別の機会に。

全体として、BSDとLinuxではドキュメントの扱い方に技術的・文化的な隔たりがあるようで、まだよく理解できていませんが、BSDの世界で何が起きているのか興味を持っています。

コメントセクションはこちら。