Notes on clarifying man pages

2026-02-18

manページをわかりやすくするためのメモ

こんにちは！昨年、Gitのmanページにしばらく取り組んだあと、良いmanページとは何だろうと改めて考えるようになりました。

私は、manページが主なドキュメントになっているツール（tcpdumpやgit、digなど）のチートシートを書くのに、ずいぶん時間を費やしてきました。欲しい情報にたどり着くまで、manページの中を探し回るのが難しいと感じることが多いからです。

最近、ふと思ったのです。manページ自体の中に、すばらしいチートシートを入れることはできないだろうか、と。どうすればmanページはもっと使いやすくなるのでしょうか。まだ考え始めたばかりですが、思いついたことを簡単にメモしておきたいと思います。

Mastodonでみなさんにお気に入りのmanページを聞いてみたところ、そこで見つけたおもしろい工夫をいくつか紹介します。

OPTIONS SUMMARY（オプション一覧）

manページをたくさん読んだことがある方なら、SYNOPSISでこんな記述を見たことがあるかもしれません。アルファベットのほぼすべてを並べるようになると、とても読みづらくなります。

ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]

grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]

rsyncのmanページには、これまで見たことのない解決策がありました。SYNOPSISを次のようにとても簡潔にまとめているのです。

 Local:
     rsync [OPTION...] SRC... [DEST]

そして「OPTIONS SUMMARY」というセクションで、各オプションを1行で要約して並べています。例えばこんな感じです。

--verbose, -v            increase verbosity
--info=FLAGS             fine-grained informational verbosity
--debug=FLAGS            fine-grained debug verbosity
--stderr=e|a|c           change stderr output mode (default: errors)
--quiet, -q              suppress non-error messages
--no-motd                suppress daemon-mode MOTD

その後に、通常のOPTIONSセクションが続き、各オプションの詳しい説明が載っています。

カテゴリ別に整理されたOPTIONSセクション

straceのmanページでは、オプションがアルファベット順ではなく、「General」「Startup」「Tracing」「Filtering」「Output Format」といったカテゴリ別に整理されています。

試しにgrepのmanページを題材に、カテゴリ別に分けた「OPTIONS SUMMARY」を作ってみました。結果はこちらでご覧いただけます。出来栄えについては自分でもまだ何とも言えませんが、楽しい実験でした。これを書いているとき、grepの-lオプションの名前がどうしても覚えられないことを考えていました。manページの中で探すのに毎回とても時間がかかる気がして、どういう構成ならもっと見つけやすくなるだろうかと考えたのです。カテゴリ分けなら、見つけやすくなるかもしれません。

チートシート

何人かの方にPerlの一連のmanページ（perlfuncやperlreなど）を教えてもらい、その中で気になったのがman perlcheatです。次のようなチートシート形式のセクションがあります。

 SYNTAX
 foreach (LIST) { }     for (a;b;c) { }
 while   (e) { }        until (e)   { }
 if      (e) { } elsif (e) { } else { }
 unless  (e) { } elsif (e) { } else { }
 given   (e) { when (e) {} default {} }

これはとても素敵だと思います。manページの中で使える、80文字幅のコンパクトなASCIIチートシートには、他にどんな書き方があり得るのだろうと考えさせられます。

使用例はとても人気があります

多く寄せられたのが「使用例が載っているmanページが好き」という趣旨のコメントでした。OpenBSDのmanページを挙げてくれた方もいて、OpenBSDのtailのmanページの最後には、まさに私が普段使っている2通りの使い方が例として載っていました。

EXAMPLESセクションはmanページの最後にあることが多いと思いますが、先ほどのrsyncのmanページのように、冒頭から使用例を載せているものもあります。git-addやgit rebaseのmanページに取り組んだときは、私も冒頭に短い使用例を入れました。

目次とセクション間のリンク

これはmanページ自体の性質というより、端末でmanページを読むときの問題なのですが、そもそもそのmanページにどんなセクションがあるのかが分かりづらいという点があります。

Gitのmanページに取り組んだとき、Marieと私がやったことのひとつが、Gitサイトで公開されているHTML版のmanページのサイドバーに目次を追加することでした。

いずれはHTML版のGit manページにもっとハイパーリンクを追加して、「INCOMPATIBLE OPTIONS」をクリックすればそのセクションに飛べるようにしたいと思っています。GitのmanページはAsciiDocで生成されているので、このようなリンクを追加するのはとても簡単です。

目次や内部リンクを追加するのは、まったく別のドキュメント形式を別途維持することなく、manページのフォーマット（少なくともHTML版）を改善できる、ほどよい中間案だと思います。ただ、これを実現するにはGitのAsciiDocシステムのようなツールチェーンを用意する必要があります。

manページの中で特定のオプションを簡単に調べられる（「-aは何をするんだっけ？」といった具合に）汎用的な仕組みがあれば素晴らしいなと思います。私が知るかぎり一番良い方法は、manのページャーで^ *-aのように検索することですが、つい忘れてしまい、結局manページ内の-aをひとつひとつ追っていって、ようやく目的の箇所を見つけることになります。

すべてのオプションに使用例を

curlのmanページにはすべてのオプションに使用例があり、HTML版には目次もあるので、知りたいオプションへ簡単にジャンプできます。

たとえば--certの使用例を見ると、--keyオプションも一緒に渡す必要があることがすぐに分かります。こんな感じです。

  curl --cert certfile --key keyfile https://example.com

実装方法としては、[オプションごとに1ファイル用意し](https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md)、そのファイル内に「Example」フィールドを設ける形になっています。

表形式でのデータ表示

かなり多くの方がman asciiをお気に入りのmanページとして挙げてくれました。内容はこんな感じです。

 Oct   Dec   Hex   Char                     
 ───────────────────────────────────────────
 000   0     00    NUL '\0' (null character)
 001   1     01    SOH (start of heading)   
 002   2     02    STX (start of text)      
 003   3     03    ETX (end of text)        
 004   4     04    EOT (end of transmission)
 005   5     05    ENQ (enquiry)            
 006   6     06    ACK (acknowledge)        
 007   7     07    BEL '\a' (bell)          
 010   8     08    BS  '\b' (backspace)     
 011   9     09    HT  '\t' (horizontal tab)
 012   10    0A    LF  '\n' (new line)

もちろんman asciiは少し変わったmanページですが、ASCIIリファレンスとしていつでも役立つという点以外で素晴らしいのは、表形式になっているおかげで必要な情報をざっと眺めてすぐに見つけられることです。manページの中でも、もっと情報を「表」で見せて探しやすくできる場面があるのではないかと考えさせられます。

GNUのアプローチ

manページの話をすると、よく話題になるのが、GNU coreutilsのmanページ（たとえばman tail）には使用例がなく、使用例があるOpenBSDのmanページとは対照的だということです。

これはかなり政治的な話題でもあるようですし、ここで十分に論じることはできないので深くは立ち入りませんが、私が正しいと理解していることをいくつか挙げておきます。

GNUプロジェクトはmanページではなく「info」マニュアルでドキュメントを管理することを好んでいます。こちらのページには「manページはもはやメンテナンスされていません」と書かれています。
「info」マニュアルを読む方法は3つあります。HTML版、Emacsの中、そしてスタンドアロンのinfoツールです。Emacsユーザーからは、Emacsのinfoブラウザが気に入っているという話を聞いたことがあります。一方で、スタンドアロンのinfoツールを使っているという人には、会ったことがないと思います。
tailのinfoマニュアルはmanページの末尾でリンクされており、そちらには使用例が載っています。
FSFはかつてGNUソフトウェアマニュアルの印刷版を販売していました（今もときどき販売しているのかもしれません）。

ある程度以上に複雑になると、manページは本当に探しづらくなります。coreutilsのinfoマニュアルは使ったことがありませんし、おそらく今後も使わないと思いますが、GNU BashリファレンスマニュアルやThe GNU C Library Reference Manualであれば、manページではなくHTML版のドキュメントで読みたいと強く思います。

manページ周辺のもう少し気になること

興味深いと思うツールをいくつか挙げてみます。

fish shellには、manページからタブ補完を自動生成するPythonスクリプトが付属しています。
tldr.shはコミュニティによって維持されている使用例のデータベースで、たとえばtldr grepのように実行できます。役に立つと教えてくれた方がたくさんいました。
DashというMac用のドキュメントブラウザには、優れたmanページビューアが組み込まれています。私は今でも端末のmanビューアを使っていますが、目次が付いているのが気に入っています。見た目はこんな感じです。

制約のあるフォーマットについて考えるのはおもしろい

manページはとても制約の多いフォーマットですが、そんな限られた表現の中で何ができるかを考えるのは楽しいものです。

文章を書くのは大好きなのに、ドキュメントをまったく読まないという悪い癖がずっとあって、manページの何が本当に役立つのかを考えるのが少し難しいと感じています。この記事で挙げたことのほとんどが、自分の体験を本当に良くしてくれるのかどうか、正直よく分かりません。（使用例だけは別です。使用例は大好きです）

そこで、みなさんが「よくできている」と思うmanページや、その理由をぜひ聞かせてください。コメント欄はこちらです。