こんにちは！昨年Gitのmanページに取り組むのにしばらく時間を費やしたあと、どんな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」セクションを作ってみました。結果はこちらで見られます。出来栄えをどう思うかは自分でもまだわかりませんが、楽しい実験でした。これを書いているとき、-lというgrepのオプション名がどうしても覚えられないことを考えていました。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で凝縮されたチートシートの書き方が、他にもあるのではないかと考えさせられます。

examplesは大人気

よくあったコメントは、「例が載っているmanページなら何でも好き」といった趣旨のものでした。誰かがOpenBSDのmanページを挙げてくれましたが、OpenBSDのtailのmanページには、まさに私がtailを使う2通りの例が最後に載っています。

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

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

これはmanページ自体の性質ではありませんが、ターミナルでmanページを読むときの問題のひとつは、どんなセクションがあるのかがわかりにくいことです。

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

いずれはGitのmanページのHTML版にもっとハイパーリンクを追加して、「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ページですが、このmanページのクールなところは（ASCIIリファレンスとしていつも役に立つという点以外にも）表形式になっているおかげで、必要な情報をざっと眺めて見つけやすいことだと思います。manページの中でもっと情報を「表」で表示して見やすくする余地があるのではないかと考えさせられます。

GNUのアプローチ

manページの話をすると、GNU coreutilsのmanページ（たとえばman tail）には例がないのに、OpenBSDのmanページには例があるという話題がよく出ます。

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

• GNUプロジェクトは、manページではなく「info」マニュアルでドキュメントを維持することを好んでいます。このページには「the man pages are no longer being maintained」と書かれています。
• 「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のように実行できます。多くの人から役に立つと聞いています。
• Mac用のドキュメントブラウザであるDashには、優れたmanページビューアが内蔵されています。私は今でもターミナルのmanページビューアを使っていますが、目次が付いているのが気に入っています。見た目はこんな感じです。

制約のあるフォーマットについて考えるのは面白い

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

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

なので、みなさんがよくできていると思う他のmanページや、その気に入っている点についてぜひ聞いてみたいです。コメント欄はこちらです。