manページは素晴らしい、問題はmanリーダーだ

• manページが「相互リンクがない」あるいは「ターミナルウィンドウを狭めてもテキストが再整形されない」と批判されることは多いが、実際には manフォーマット自体がリンク機能と再整形機能をサポートしている
• 問題は manページを読むツール（manコマンドやlessなど） がこれらの機能を適切に実装していないことにある

manページのフォーマット構造

• man文書は主に2つのフォーマットで書かれている:
  • mdoc(7): 現代的で意味ベースのマークアップフォーマット
  • man(7): 1979〜1989年に使われていた旧式フォーマット
• 例（mdoc構文の一部）:

  .Sh NAME  
  .Nm openrc  
  .Nd stops and starts services for the specified runlevel  
  .Sh SYNOPSIS  
  

• .Sh、.Nm、.Nd はそれぞれセクション見出し、コマンド名、説明を意味する
• 直接編集するには、mdocマクロ一覧を参照する必要がある

参照（リンク）機能も組み込まれている

• mdocフォーマットには次のようなリンクマクロが含まれている:
• .Xr: 他のmanページを参照するクロスリファレンス
• .Sx: 同じページ内の別セクションへの参照
• HTMLに変換すると実際のリンクとしてレンダリングされ、ブラウザでクリックできる
• .Sh セクション見出しはアンカーとして扱われ、.Sx リンクのリンク先になれる
• しかし、ターミナルで man コマンドから表示すると、このリンク機能は動作しない

結論: 問題はmanフォーマットではなくビューアにある

• 現在の man コマンドはページを less にパイプして表示しているため、この方式ではリンクを処理できない
• 解決策は次のとおり:
• manフォーマットを理解し、リンクをサポートする新しいページビューアが必要
• ターミナル幅の変更時に テキストの自動再整形（reflow） 機能もあわせて実装すればさらによい

背景情報

• mdoc(7) は1990年代の4.4BSDで導入されたフォーマット
• man(7) は1979年〜1989年の間に使われていた古典的フォーマットで、現在はほとんど使われていない

[scari]

Slackボットの通知で1行目だけ見てすぐ共感してクリックしました。私もリーダーが問題だという指摘に100%同意します。

…でも、現代人は man はおろかターミナルも使わないみたいなんですよね。rtfm はロマンの時代の遺物になってしまいましたね。

[winterjung]

私は mac では次のように定義しておいて、pman ls のように使って PDF で見ています。

pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  

[pcj9024]

すごく役立つヒントですね……ありがとうございます

[pkj3186]

すごい、本当にありがとうございます

[bbulbum]

わあ、これは本当に共感します。man はちゃんと読めば本当に素晴らしいのですが、うまく読むのがとても難しいんですよね..

[GN⁺]

Hacker Newsの意見

• 長年にわたってmdocやmandb形式の文書を書いてきたが、その言語を習得するのは難しいという意見がある
  • mdocとmandbはroffの上にあるマクロセットのようなもの
  • すべてのmanページをMarkdownに変換してシステム上で表示することを提案したいと考えている
  • Markdownにはより多くのツールがあり、非技術系のユーザーでも簡単に文書を作成できる
  • しかしMarkdownは形式性が低く、さまざまなプログラムで異なる方言が存在する
• Emacsでinfoページを閲覧するのは便利で、manページでも似たようなことができる
  • 既存のmanページの豊かさは、多くの人が認識していない利点である
  • Markdownへ移行しようとする人たちに対する惜しさがある
  • Markdownに移行すると、既存ソリューションのリンクや一般的なセマンティクスを実装するのが難しくなるだろう
  • データをJSONに移した事例を見ると、複雑な機能を追加しようとする試みがある
• Vimの組み込みft-man-pluginをデフォルトのmanページとして使うことが、問題解決に役立つ
  • リンクが機能し、改行時にもインデントを維持する
  • lessのデフォルト設定は改善できるが、水平スクロールが必要になる
• 多くのWeb版manページが等幅フォントに設定されていて残念
  • OpenBSDのオンラインmanページは素晴らしい
  • ターミナルでmanページを読むのも良い
  • 検索機能と半ページスクロールを主に使っている
• pinfoはGNU Infoページを見るためのものだが、manページも表示できる
  • ページ間の相互参照を認識して移動できる
• 特定のフラグの説明へ移動する機能があればよいという意見がある
  • 現在は正規表現を使ってフラグの説明を探している
• mandocプロジェクトを検討することを提案
  • ページをセマンティックに処理して、より良い結果を得られる
• Markdownのほうがより良い解決策だという意見がある
  • Webやコードエディタで文書を読むことに慣れているため、ほかのインターフェースは不便
  • 開発者はMarkdownに慣れており、ほとんどの文書もMarkdownで書かれている
  • manページは文書の作成者と利用者の両方にとって劣っている