man pageの書き方

This content is a draft and will not be included in production builds.

troffマクロの基本

troff マクロは引数を受け取れる。このとき空白で引数を区切るので、スペースを含む文字列を1つの引数として渡したい場合は以下のようにクオートするかエスケープする。

.B "an apple"
.B an\~apple
.B an\ apple

また、GNUの場合は引数の個数に制限はないが、最大6個までの制限を持つ実装もある。

troffテキスト出力の行詰めと位置揃えで詰める設定になっていると目立たないが、単に空行を書くとテキストの一部として認識されてしまう。これを避けるために . を置く。

.TH aaa
.SH SYNOPSIS
.
.SH DESCRIPTION

\" の後から行末までがコメントになる。このときも空行と同様に、意図しない行が残らないよう先頭に . を置く。

.\" コメント
.SH BUGS \" これもコメント
\" これだと空行が残る

マニュアルは troff マクロなので、troff のコマンドをそのまま書ける。このとき例えば以下の文字は troff によって扱われるのでエスケープが必要になる。

文字	エスケープ
`\`	`\e`, `\(rs`
`"`	`\(dq`

他にも色々あるのでtroffにおける特殊文字に分割した。

マニュアルを書くとき頻繁に登場するマクロの使い方をまとめる。

典型的には

.SH OPTIONS
.TP
\fB\-a\fR, \fB\-\-all\fR=\fIOPT\fR
usage text

たぶんこれでもいい

.TP
.BI \-a\fR= OPT
usage text

リンクを表現する。

.UR https://example.com/
Example
.UE

.UE の後に書いた文字はリンクテキストと繋げて描画される。

The
.UR https://example.com/
Example
.UE 's
Homepage