manの読み方（初心者向け）

基本的にLinuxを前提にしています。

# セクション

manページは1～8のセクションに分かれている。

1. コマンド
2. システムコール
3. ライブラリ関数（C言語）
4. スペシャルファイル（/dev/）
5. 設定ファイル
6. ゲーム
7. 雑多な事（慣習、プロトコル、文字コードなど）
8. システム管理

例えば`man printf`とするとセクション1の`printf`コマンドのmanが表示される。
C言語の`printf`関数のmanを見たいときは`man 3 printf`のようにセクション番号を指定する。
`man -a printf`のように`-a`をつけると、全てのセクションで見つかったものを順番に表示する。

C言語の関数名やシステムコール名を`fork(2)`や`printf(3)`のように数字つきで書くことがあるが、これは引数ではなく、manのセクション番号を表している。つまり`fork`はシステムコールで、`printf`はライブラリ関数である。


# SYNOPSISの表記法

以下の`man man`を例にとって説明する。
http://man7.org/linux/man-pages/man1/man.1.html

<b>SYNOPSIS</b>
　　　　<b>man </b>[<b>-C </b><i>file</i>] [<b>-d</b>] [<b>-D</b>] [<b>--warnings</b>[=<i>warnings</i>]] [<b>-R </b><i>encoding</i>] [<b>-L</b>
　　　　<i>locale</i>] [<b>-m </b><i>system</i>[,...]] [<b>-M </b><i>path</i>] [<b>-S </b><i>list</i>] [<b>-e </b><i>extension</i>] [<b>-i</b>|<b>-I</b>]
　　　　[<b>--regex</b>|<b>--wildcard</b>] [<b>--names-only</b>] [<b>-a</b>] [<b>-u</b>] [<b>--no-subpages</b>] [<b>-P</b>
　　　　<i>pager</i>] [<b>-r </b><i>prompt</i>] [<b>-7</b>] [<b>-E </b><i>encoding</i>] [<b>--no-hyphenation</b>]
　　　　[<b>--no-justification</b>] [<b>-p </b><i>string</i>] [<b>-t</b>] [<b>-T</b>[<i>device</i>]] [<b>-H</b>[<i>browser</i>]]
　　　　[<b>-X</b>[<i>dpi</i>]] [<b>-Z</b>] [[<i>section</i>] <i>page</i> ...] ...
　　　　<b>man -k </b>[<i>apropos options</i>] <i>regexp</i> ...
　　　　<b>man -K </b>[<b>-w</b>|<b>-W</b>] [<b>-S </b><i>list</i>] [<b>-i</b>|<b>-I</b>] [<i>--regex</i>] [<i>section</i>] <i>term</i> ...
　　　　<b>man -f </b>[<i>whatis options</i>] <i>page</i> ...
　　　　<b>man -l </b>[<b>-C </b><i>file</i>] [<b>-d</b>] [<b>-D</b>] [<b>--warnings</b>[=<i>warnings</i>]] [<b>-R </b><i>encoding</i>] [<b>-L</b>
　　　　<i>locale</i>] [<b>-P </b><i>pager</i>] [<b>-r </b><i>prompt</i>] [<b>-7</b>] [<b>-E </b><i>encoding</i>] [<b>-p </b><i>string</i>] [<b>-t</b>]
　　　　[<b>-T</b>[<i>device</i>]] [<b>-H</b>[<i>browser</i>]] [<b>-X</b>[<i>dpi</i>]] [<b>-Z</b>] <i>file</i> ...
　　　　<b>man -w</b>|<b>-W </b>[<b>-C </b><i>file</i>] [<b>-d</b>] [<b>-D</b>] <i>page</i> ...
　　　　<b>man -c </b>[<b>-C </b><i>file</i>] [<b>-d</b>] [<b>-D</b>] <i>page</i> ...
　　　　<b>man </b>[<b>-?V</b>]
</div>
表記法の意味:

       太字                そのままタイプするテキスト
       斜体 or 下線         適切な引数で置き換えるべきテキスト
       [-abc]             [ ] の中は省略可能。-a -b -cの任意の組み合わせ
       -a|-b              どちらか一方
       argument ...       ... は繰り返しを意味する
       [expression] ...   [ ] の中全体の繰り返し

ごく稀にこのルールに従っていないmanもあるが、このルールは覚えておくとよいと思う。

伝統的な記法では「適切な値で置き換えるべきテキスト」を斜体or下線で表すが、最近では `<>` で囲んで表すコマンドも多い（例 `git clone <repository>`）



この`man man`の場合は8種類の構文が表示されているが、それぞれ別の構文と考えるべき。例えば

```
       man -w|-W [-C file] [-d] [-D] page ...
       man -c [-C file] [-d] [-D] page ...
```

と書いてあるので`-w`と`-c`いうオプションがあることが分かるが、これらは同時には使えない。

```
$ man -w -c ls
man: -c -w : 相互に利用できないオプションです
Try 'man --help' or 'man --usage' for more information.
```

man pageの表記法や慣習について詳しくは`man 7 man-pages`に書いてある。
http://man7.org/linux/man-pages/man7/man-pages.7.html
（ちなみにこのman7.orgの運営者はマイケル・ケリスク。かのバイブル[「Linuxプログラミングインタフェース」](http://www.amazon.co.jp/dp/487311585X/)の著者）

セクション7にはけっこう面白いものがあるので暇な時に眺めてみることをおすすめ。

## 自分でmanページや--helpを書く場合は

docoptを参考にすると良いかもしれない。これがデファクトスタンダードと言えるかは議論の余地があるが、`--help`を書く時の、一つの標準を示してくれている。Pythonのライブラリなので、Pythonで書いている場合は色々な恩恵を受けられる。
http://docopt.org/


# 気をつけること

コマンドのmanを見るときは、設定ファイルのmanがセクション5にないかも確認するとよい。たいていは末尾のSEE ALSOに書いてある。例えば`man crontab`とするとcrontabコマンドが表示されるが、SEE ALSOに`crontab(5)`と書いてあるので、`man 5 crontab`で設定の書き方が読めることが分かる。

Linuxは雑多なパッケージの寄せ集めなので、SEE ALSOに書いてあるman pageがない場合もある。

日本語に翻訳されているmanは古いものが多い。`LANG=C man`で英語版を確認したい（オプションが増えていることがよくある）。

末尾に「GNU coreutils 8.22」のようにコマンドの所属パッケージが書いてある事が多い。パッケージを意識しておくと次のようなメリットがある。

* 「これはcoreutilsに含まれているからちゃんとメンテナンスされているだろう」とか「他のディストロでも使えるだろう」と当たりがつけられる。
* パッケージの公式サイトに行くともっと詳細なドキュメントがある場合がある。特にGNUのパッケージはinfoの方が詳しい

# Tips

## ASCII文字コード表

`man ascii`でASCII文字コード表を表示できる。

## C言語の演算子の優先順位

`man operator`

## manファイルの置き場所

通常は`/usr/share/man/`に置いてある。
`man -w ls`のようにしてmanファイルの場所を調べられる。
環境変数`$MANPATH`を指定すると、それ以外の検索パスを追加できる。このとき`MANPATH=:/path-to-man`のように先頭にコロンをつけないと、それ以外のパスが検索されなくなってしまうので注意。

## ファイルを指定

`man ./latin1.7.gz`のようにmanファイルへのパスを指定すると、そのファイルを表示できる。





## manのカラー化

以下を`~/.bashrc`（または`~/.zshrc`）に書いておくと、manの太字と下線の部分が色付けされるようになる。

```~/.bashrc
man() {
    env GROFF_NO_SGR=1 LESS_TERMCAP_mb=$'\E[01;31m' \
    LESS_TERMCAP_md=$'\E[01;38;5;74m' \
    LESS_TERMCAP_me=$'\E[0m' \
    LESS_TERMCAP_se=$'\E[0m' \
    LESS_TERMCAP_so=$'\E[38;5;246m' \
    LESS_TERMCAP_ue=$'\E[0m' \
    LESS_TERMCAP_us=$'\E[04;38;5;146m' \
    man "$@"
}
```

色は31, 74, 246, 146の部分を置き換えれば変えられる。
色番号の一覧：http://www.calmar.ws/vim/256-xterm-24bit-rgb-color-chart.html

mb＝ブリンクモード開始, md＝ダブルブライトモード開始, mb＝装飾モード終了
se＝強調終了、so＝強調開始、ue＝下線終了、us＝下線開始
http://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html#SEC44

~~参考：[ArchWiki: man ページ](https://wiki.archlinux.jp/index.php/Man_%E3%83%9A%E3%83%BC%E3%82%B8)~~ カラー化の記述は削除されたようだ

[2023-10-15追記]
最近、Archで上記のカラーが効かなくなった。 `GROFF_NO_SGR=1` を追加したら直った。
参考: [colors - Colored man pages not working on gentoo - Unix & Linux Stack Exchange](https://unix.stackexchange.com/questions/6010/colored-man-pages-not-working-on-gentoo)


## トリビア：長大なmanページトップ20
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/79394/7414c53e-f621-61a6-f043-8a6957fb2efb.png)
https://www.reddit.com/r/linux/comments/13b45g3/top_20_largest_man_pages/ より