こんにちは！ 昨年、Git の man ページの作業に時間を費やした後、 優れた man ページとは何かをもう少し考えてみました。

私は tcpdump、git、dig などのツールのチートシートを書くことに多くの時間を費やしてきました。 これらのツールは主なドキュメントとして man ページを持っています。これは、必要な情報を見つけるために man ページを操作しにくいと感じることが多いからです。

最近、man ページ自体に素晴らしいチートシートを含めることはできないだろうか？ と考えています。 man ページを使いやすくするには何が必要でしょうか？ まだ考え始めたばかりですが、いくつかの簡単なメモを書いてみました。

私は Mastodon で人々に好きな man ページを尋ね、それらの man ページで見つけた興味深い例をいくつか挙げます。

OPTIONS SUMMARY

man ページをたくさん読んだことがある人なら、SYNOPSIS に次のような記述を見たことがあるでしょう。一度アルファベット全体をほぼ列挙し始めると、理解しにくくなります。

ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]

grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]

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

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

その後、各オプションの 1 行の要約を含む「OPTIONS SUMMARY」セクションを設けています。例：

--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 チートシートを書く他の方法があるのではないかと考えています。

例が非常に人気

よく聞かれるコメントに、「例が載っている man ページが好き」というものがあります。OpenBSD の man ページを挙げてくれた人がいて、openbsd tail の man ページには、私が tail を使う 2 つの方法の正確な例が最後に載っています。

EXAMPLES セクションは man ページの最後に置かれることが多いですが、rsync の man ページ のように冒頭に例を置くものもあります。git-add と git rebase の man ページを作成したときは、冒頭に短い例を入れました。

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

これは man ページ自体の性質ではありませんが、ターミナルでの man ページの問題の 1 つは、man ページにどのようなセクションがあるかを知るのが難しいことです。

Git の man ページを作成する際、Marie と私は Git サイトでホストされている man ページの HTML 版のサイドバーに目次を追加しました。

また、Git の man ページの HTML 版にさらにハイパーリンクを追加したいと考えています。これにより、「INCOMPATIBLE OPTIONS」をクリックしてそのセクションに移動できるようになります。Git の man ページは AsciiDoc で生成されているため、このようなリンクを追加するのは非常に簡単です。

目次と内部ハイパーリンクを追加することは、man ページ形式（少なくとも HTML 版の man ページ）に対して、まったく異なる形式のドキュメントを維持することなく、いくつかの改善を行うための良い中間地点だと思います。ただし、これを実現するには 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」マニュアルでドキュメントを維持することを好みます。このページ には「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 ページに関連するその他のこと

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

  • The fish shell には man ページからタブ補完を自動生成する Python スクリプト が付属しています。
  • tldr.sh はコミュニティが管理する例のデータベースで、tldr grep のように実行できます。多くの人が役立つと言っています。
  • Dash Mac ドキュメントブラウザには優れた man ページビューアが搭載されています。私はまだターミナルの man ページビューアを使っていますが、目次が含まれているのが気に入っています。次のようになります。
dash.webp

制約のある形式について考えるのは面白い

man ページは非常に制約のある形式であり、限られた書式オプションで何ができるかを考えるのは楽しいことです。

私は執筆が好きですが、ドキュメントをほとんど読まないという悪い習慣があり、man ページで実際に何が役立つかを考えるのは少し難しいです。この記事のほとんどが私の体験を改善するかどうかはわかりません。（例を除いて、例は大好きです）

したがって、よく設計されていると思う他の man ページや、それらについて気に入っている点についてお聞きしたいです。 コメントセクションはこちら。