マニュアルページの明確化に関する注意事項
こんにちは！昨年、Git のマニュアル ページの作業に時間を費やした後、優れたマニュアル ページとは何かについてもう少し考えてみました。
私は、主要なドキュメントとしてマニュアルページを持つツール (tcpdump、git、dig など) のチートシートを書くのに多くの時間を費やしてきました。これは、必要な情報を取得するために man ページをナビゲートするのが難しいと感じることがよくあるためです。
最近私は疑問に思っています – man ページは可能でしょうか？ 自体 素晴らしいカンニングペーパーが入っていますか？ man ページを使いやすくするにはどうすればよいでしょうか?これについてはまだ考え始めたばかりですが、簡単にメモしておきたいと思います。
私はマストドンの何人かの人々にお気に入りの man ページを尋ねました。ここでは、それらの man ページで見た興味深いものの例をいくつか紹介します。
オプションの概要
マニュアルページをたくさん読んだことがあるなら、おそらく次のような内容を見たことがあるでしょう。 SYNOPSIS: アルファベットのほぼ全体をリストすると、それは困難です
ls (-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,)
grep (-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz)
rsync の man ページには、これまで見たことのない解決策が記載されています。次のように、その概要は非常に簡潔です。
Local:
rsync (OPTION...) SRC... (DEST)
次に、次のように各オプションの 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 のマニュアル ページでは、オプションがアルファベット順ではなくカテゴリ (「全般」、「スタートアップ」、「トレース」、「フィルタリング」、「出力形式」など) 別に整理されています。
実験として、撮ってみました grep man ページを開き、カテゴリごとにグループ化された「オプションの概要」セクションを作成すると、ここで結果を確認できます。結果についてどう思うかはわかりませんが、楽しい練習でした。これを書いているとき、どうしてその名前を思い出せないのか考えていました。 -l grep オプション。マニュアルページでそれを見つけるのはいつも永遠のように感じられますが、どのような構造にすれば見つけやすくなるかを考えていました。もしかしてカテゴリー？
チートシート
何人かの人々が私に一連の Perl マニュアルページを教えてくれました (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 {} }
これはとても素晴らしいと思いますし、マニュアルページで使用するための、80 文字幅の圧縮された ASCII チートシートを作成する他の方法はないのかと疑問に思います。
例は非常に人気があります
よくあるコメントは、「例がある man ページはどれも好きです」という趣旨のものでした。誰かが OpenBSD のマニュアル ページについて言及しましたが、openbsd tail のマニュアル ページの最後には、私が tail を使用する正確な 2 つの方法の例が記載されています。
マニュアルページの最後にある「例」セクションをよく見たと思いますが、一部のマニュアルページ (先ほどの rsync マニュアルページなど) は例から始まります。 git-add および git rebase のマニュアル ページで作業していたとき、最初に短い例を置きました。
目次とセクション間のリンク
これはマニュアル ページ自体の特性ではありませんが、ターミナル内のマニュアル ページに関する問題の 1 つは、マニュアル ページにどのようなセクションがあるかを知るのが難しいことです。
Git のマニュアル ページで作業するときに、マリーと私が行ったことの 1 つは、Git サイトでホストされているマニュアル ページの HTML バージョンのサイドバーに目次を追加することでした。
また、いつか Git マニュアル ページの HTML バージョンへのハイパーリンクを追加して、「INCOMPATIBLE OPTIONS」をクリックしてそのセクションにアクセスできるようにしたいと考えています。 Git のマニュアル ページは AsciiDoc で生成されるため、Git プロジェクトにこのようなリンクを追加するのは非常に簡単です。
目次の追加と内部ハイパーリンクの追加は、ドキュメントのまったく異なる形式を維持することなく、マニュアル ページの形式 (少なくとも HTML バージョンのマニュアル ページ) にいくつかの改善を加えることができる、ある種の優れた中間点だと思います。ただし、これを機能させるには、Git の AsciiDoc システムのようなツールチェーンをセットアップする必要があります。
マニュアルページで特定のオプション (「-a は何をするのか?」など) を簡単に検索できるような、ある種の汎用システムがあれば素晴らしいでしょう。私が知っている最善の方法は、man ページャーを使用して次のようなものを検索することです。 ^ *-a
しかし、私はそれをすることを決して覚えておらず、代わりに、すべてのインスタンスを通過することになります。 -a 探しているものが見つかるまでマニュアルページを参照してください。
すべてのオプションの例
Curl のマニュアル ページにはすべてのオプションの例があり、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 これは珍しいマニュアル ページですが、このマニュアル ページの優れている点は (ASCII リファレンスがあると常に便利であるという点を除けば)、テーブル形式であるため、必要な情報を見つけるためにざっと目を通すのが非常に簡単であることだと思います。読みやすくするために、マニュアルページの「表」に情報を表示する機会がもっとあるのではないかと思います。
GNU アプローチ
マニュアルページについて話すとき、サンプルがある OpenBSD マニュアルページとは異なり、GNU coreutils マニュアルページ (たとえば、man tail) にはサンプルがないことがよく話題になります。
かなり政治的な話題のようで、ここで正確に説明することは絶対にできないので、これについてはあまり立ち入るつもりはありませんが、私が真実だと信じていることがいくつかあります。
- GNU プロジェクトは、マニュアル ページではなく「情報」マニュアルでドキュメントを維持することを好みます。このページには「マニュアルページはもうメンテナンスされていません」と書かれています。
- 「情報」マニュアルを読むには 3 つの方法があります: HTML バージョン、Emacs、またはスタンドアロンで読む
info道具。何人かの Emacs ユーザーから、Emacs 情報ブラウザが気に入っていると聞いたことがあります。スタンドアロンを使用している人と話したことはないと思いますinfo道具。 - tail の情報マニュアルエントリはマニュアルページの下部にリンクされており、例が含まれています
- FSF は、GNU ソフトウェア マニュアルの印刷本を販売していました (おそらく今でも時々販売しているのではないでしょうか?)
ある程度複雑になると、マニュアル ページは非常にナビゲートしにくくなります。私は coreutils 情報マニュアルを使用したことがありませんし、おそらく今後も使用しないでしょうが、ほぼ確実に、マニュアル ページではなく HTML ドキュメント経由で GNU Bash リファレンス マニュアルまたは GNU C ライブラリ リファレンス マニュアルを使用することを好みます。
マニュアルページに隣接するものをさらにいくつか
私が興味深いと思うツールをいくつか紹介します。
- Fish Shell には、マニュアルページからタブ補完を自動的に生成する Python スクリプトが付属しています。
- tldr.sh は、コミュニティが管理するサンプルのデータベースです。たとえば、次のように実行できます。
tldr grep。多くの人が便利だと言ってきました。 - Dash Mac ドキュメント ブラウザには、優れた man ページ ビューアが組み込まれています。私はまだターミナルの man ページ ビューアを使用していますが、次のような目次が含まれているのが気に入っています。
制約のあるフォーマットについて考えるのは興味深いです
マニュアルページは非常に制約された形式なので、そのような限られた形式オプションで何ができるかを考えるのは楽しいです。
私は文章を書くことにとても興味があるにもかかわらず、ドキュメントをまったく読まないという悪い癖があり、マニュアルページで実際に役立つと思うものを考えるのが少し難しいです。この投稿にあるほとんどのことが私の経験を向上させるかどうかはわかりません。 (例を除いて、私は例が大好きです)
そこで、あなたがよく設計されていると思う他のマニュアルページと、そのマニュアルページのどこが気に入っているかについて知りたいです。コメントセクションはここにあります。
