manページの書き方
研究室で開発しているプログラムSLIMのmanページを作ってみた。以下メモ的なまとめ。
-
-
- -
-
manページの基本はhttp://www.linux.or.jp/JF/JFdocs/Man-Page.htmlにまとまっている。ひとつ、知っておくべき事はmanページは以下のようなセクション番号で分類されることだ。
| 番号 | 説明 | |
|---|---|---|
| 1 | コマンド(プログラム) | |
| 2 | システムコール | |
| 3 | ライブラリ関数 | |
| 4 | /dev以下のスペシャルファイル | |
| 5 | ファイルのフォーマット | |
| 6 | ゲーム | |
| 7 | その他、仕様や慣習など様々な事 | |
| 8 | システム管理のコマンド |
manページを書くためには man(7), man-pages(7)を見れば良い。
$ man 7 man
$ man 7 man-pages
とコマンドを入力すれば見ることが出来る。どちらもセクション7のページで、man(7)はmanページのフォーマット，man-pages(7)はLinuxでのmanページの慣習について書いてある。もっとも、一番参考になるのはやっぱり既存のmanページのソースだけど。
準備が整った。これらを見ながら開発中のプログラムSLIMのmanページを書いてみる。
フォーマットの基本
コマンドはドットから始まる。.BRとか.SHというのがコマンドになる。
フォーマットの指定はほとんどの場合一行丸ごと使う。なので、分の途中の文字をボールドにしたいときにはコマンドの前後で改行をする必要がある。
関数
.B append
はリストを連結する。
といった具合。フォーマット自体はかなりシンプルなので難しくないが、コマンドの改行を頻繁にしなければならないなどあまり書きやすくはない。
コマンドサマリー
| コマンド | 説明 |
|---|---|
| .\" | コメント |
| .TH | メタデータ |
| .SH | セクションを作る |
| .TP | パラグラフを作る |
| .PP | パラグラフを作る |
| .br | 改行する |
| .B text | textをボールド体にする |
| .I text | textをイタリック体にする |
| .BI text | textをボールド体イタリック体交互にする |
| .I text | textをイタリック体にする |
実際の一行目に書くこと、メタデータ
(コメント行以降の)一行目にはタイトル，セクション、日付などのメタデータを含む行を書く。
形式はこうだ。
.TH title section date source manual
日付以降は面倒だから省略しよう。
.TH SLIM 1
セクション
セクション(このセクションはあくまでページ内の構造、まぎらわしいけど)は
.SH セクション名
と書く。
最初のセクションは NAME だ。ここにはコマンド名と簡単な説明を書く。注意することは、whatisやaproposコマンドの為に、コマンド名の後に \- を書くことだ。
.SH NAME
slim \- a LMNtal runtime
次にSYNOPSISセクションでコマンドとオプションの形式を書く。
.SH SYNOPSIS
.B slim
[-t]
[--version]
[--showproxy]
[--hideruleset]
[--help]
[-I
.I path
]
[-O[<0-9>] ]
[--]
[
.I program argument ...
]
次に、DESCRIPTIONセクションでコマンドの説明をする。
.SH DESCRIPTION
.I SLIM
is a LMNtal runtime.When
.I LMNtal intermediate code
is given, slim loads the code, evaluating code.
次に、OPTIONSセクションでオプションの説明をする。
.SH OPTIONS
Here is a summary of all the options.
各オプションは .TP と .BIを使って書く。.TPはパラグラフを作るコマンドで.TPの次の行がパラグラフのタグ(オプションの部分)になる。.BIはワードがボールド体とイタリック体に交互になりこの場合にはちょうど良い。
.TP
.BI -I path
Adds
.I path
to the head of the load path list.
で、あとはENVIRONMENT,AUTHORS,SEE ALSOを書いて，全体はこうなった。英語が変なのは仕様です。
.\" $Id$ -*-nroff-*-
.TH SLIM 1
.SH NAME
slim \- a LMNtal runtime
.SH SYNOPSIS
.B slim
[-t]
[--version]
[--showproxy]
[--hideruleset]
[--help]
[-I
.I path
]
[-O[<0-9>] ]
[--]
[
.I program argument ...
].SH DESCRIPTION
.I SLIM
is a LMNtal runtime.When
.I LMNtal intermediate code
is given, slim loads the code, evaluating code.If a file whose extension is .lmn is given, slim compiles the file
to a intermediate code with LMNtal system(see ENVIRONMENT), and execute the code..SH OPTIONS
Here is a summary of all the options..TP 5
.BI --version
Prints slim version and exits.
.TP
.BI -I path
Adds
.I path
to the head of the load path list.
.TP
.BI -O
.TP
.BI -Olevel
Optimization level. (-O=-O1)
.TP
.BI -t
Traces and prints the current state of execution.
.TP
.BI --showproxy
Show proxy atoms.
.TP
.BI --hideruleset
Hide ruleset from result
.TP
.BI --help
Print (on the standard output) a description of the command line
options understood by slim.
.TP
.BI --
Specifies that there are no more options. If there are more
arguments after this, they are taken as script file name and
its arguments..SH ENVIRONMENT
.TP
.B LMNTAL_HOME
.TQ
Path to the LMNtal system
.TP
.B SLIM_CFLAGS
.TQ
LMNtal compiler options.SH AUTHORS
Taisuke Hori (taisuke @ ueda . info . waseda . ac . jp).SH SEE ALSO
.PP
SLIM:
.br
http://www.ueda.info.waseda.ac.jp/slim
.PP
LMNtal:
.br
http://www.ueda.info.waseda.ac.jp/lmntal
.PP
For the information about our researches, see
http://www.ueda.info.waseda.ac.jp/
