Provided by: manpages-ja_0.5.0.0.20131015+dfsg-2_all 
名前
man - man ページを整形するマクロ
書式
groff -Tascii -man file ...
groff -Tps -man file ...
man [section] title
説明
このマニュアルページでは、 groff an.tmac のマクロパッケージ (man マクロパッケージとも呼ば
れることも多い) について説明する。 このマクロパッケージは、 Linux の man ページを書いたり
移植したりするときに、 開発者が用いるものである。 このマクロパッケージはバージョン間での互
換性が高く、 man page の移植にあたっては大きな問題はないだろう (但し、NET-2 BSD release は
例外である。 こちらでは mdoc と呼ばれる全く異なるマクロパッケージが使用されている。
mdoc(7) を参照)。
NET-2 BSD の man ページも、 groff のオプションとして -man の代わりに -mdoc を指定するだけ
で、利用することができる。 -mandoc オプションを使えばどのマクロパッケージが用いられている
か 自動的に検出できるので、このオプションを使うのがお薦めである。
Linux man-pages プロジェクトのマニュアルページを書く際に 従うべき決まり事については
man-pages(7) を参照。
タイトル行
man ページの (コメント行を除く) 最初のコマンドは、 以下のようにする必要がある。 コメント行
とは .\" で始まる行のことである。
.TH title section date source manual
TH に渡す引き数の詳細については man-pages(7) を参照。
なお BSD の mdoc フォーマットのページは TH コマンドではなく Dd コマンドから始まる。
セクション
セクションは .SH で始まり、見出し名がそれに続く。
NAME (名前) という見出しだけは必ず置かないといけない。 この見出しは一番最初のセクションに
すべきで、見出しの 次の行にはプログラムの説明を一行で書く。
.SH NAME
item \- description
このフォーマットに従い、コマンド名に続くシングルダッシュ (-) の前には必ず バックスラッシュ
を置くこと。 この文法は、 mabdb(8) プログラムが whatis(1) や apropos(1) コマンド用の短い説
明のデータベースを 生成する際に利用される。
マニュアルページに登場する可能性のあるこれ以外のセクションのリストに ついては man-pages(7)
を参照。
フォント
タイプフェイスを選択するコマンドは以下のように指定する:
.B ボールド。
.BI ボールドとイタリックとを交互に (特に関数指定に便利)。
.BR ボールドとローマンとを交互に (特に他のマニュアルページを参照するときに便利)。
.I イタリック。
.IB イタリックとボールドとを交互に。
.IR イタリックとローマンとを交互に。
.RB ローマンとボールドとを交互に。
.RI ローマンとイタリックとを交互に。
.SB スモールとボールドを交互に。
.SM スモール (頭字語などに用いる)
慣例としては、各コマンドは 6 つまでの引き数を持つ事が可能だが、 GNU の実装では制限はないよ
うだ (しかし移植性を保持するためには 引き数は 6 までに限っておくのが良いだろう)。 引き数は
スペースで区切られる。 スペースを含んだ引き数を与えるには、ダブルクォートで囲えばよい。 す
べての引き数はスペースを取り除いて並べられるので、 .BR コマンドを使えば、単語はボールド
で、句読点をローマンで表すことができる。 引き数が全く与えられなければ、 そのコマンドは次の
行のテキストに適用される。
その他のマクロや文字列
以下に、他のマクロや定義済みの文字列を示す。 特に記述がない限り、マクロを使うと改行が行わ
れる (テキストの現在の行を終了する)。 多くのマクロは 「優先インデント (prevailing
indent)」を設定したり、使用する。 優先インデントの値は、どのマクロからもパラメータ i に
よって指定できる (以下に示す)。 マクロでは i を省略することもでき、その場合は現在の優先イ
ンデントの値が用いられる。 これにより結果として、インデントされた段落が連続している場合、
インデントの値を再指定しなくてもインデント量を同じにすることができる。 通常の (インデント
されていない) 段落が登場すると、 優先インデントの値はデフォルトの値 (0.5 インチ) にリセッ
トされる。 デフォルトでは、与えたインデントの値は ens 単位である。 インデントの単位には
ens や ems を用いるとよい。これらの単位は フォントサイズが変更されると自動的に調整されるか
らである。 他の重要なマクロ定義は以下の通り:
通常の段落
.LP .PP と同じ (新たな段落の開始)。
.P .PP と同じ (新たな段落の開始)。
.PP 新しい段落を開始し、インデントをリセットする。
相対マージンインデント
.RS i 相対マージンインデント (relative margin indent) を開始する。 左マージンを i だけ
右に移動する (i が省略されると優先インデントの値が用いられる)。 新たな優先インデ
ントは 0.5 インチにセットされる。 結果として、以下の段落は対応する .RE が現れるま
でインデントされる。
.RE 相対マージンインデントを終了し、 優先インデントの値を元に戻す。
段落をインデントするマクロ
.HP i ぶらさがりインデントの段落を開始する (段落の先頭行は通常の段落の左マージンとな
り、 段落の残りの行はインデントされる)。
.IP x i インデントされた段落。オプションとしてぶらさがりタグをとる。 タグ x が省略される
と、以下の段落すべてが i でインデントされる。タグ x が与えられると、タグはインデ
ントされた段落の前にぶら下げられる (.TP とちょうど同じ。ただしタグを次の行に書く
代わりにコマンドに指定する)。 タグが長すぎる場合には、タグに続くテキストは次の行
に移動する (テキストが失われたり混ざったりすることはない)。 箇条書きをするには、
\(bu (点) あるいは \(em (ダッシュ) をタグにしてこのマクロを用いるとよい。番号付き
で箇条書きをする場合は、 数字または文字にピリオドを付けたものをタグにすればよい。
こうすれば他のフォーマットへの変換が簡単になる。
.TP i ぶらさがりタグの段落を開始する。タグは次の行に指定する。 結果は .IP コマンドと似
たものになる。
ハイパーテキストリンク用のマクロ
(groff だけでサポートされている機能) ハイパーテキストリンク用のマクロを使用するためには、
www.tmac マクロパッケージをロードする必要がある。 ロードを行うには .mso www.tmac リクエス
トを使用する。
.URL link url trailer
URI (URL) url へのハイパーテキストリンクを挿入する。 link はリンク名のテキストで
あり、 trailer の内容はリンクの直後に表示される。 HTML を生成する時に、このマクロ
は <A HREF="url">link</A>trailer という HTML コマンドに変換される。
このマクロや他の関連マクロは新しく、 多くのツールはこれらに対しては何もしないであ
ろう。 (troff を含めた) 多くのツールは未定義のマクロを単に無視するだけ (あるいは
最悪でもマクロをテキストとして挿入するだけ) なので、これらを書いても危険はない。
マニュアルページ内で自分で URL マクロを定義して、 groff 以外の roff ビューアでも
表示されるようにするのもいいだろう。 こうすることで、URL も、リンク用のテキスト
も、(もしあれば) それに続く テキストも、表示できるようになる。
以下に例を挙げる:
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ...
(later in the page)
This software comes from the
.URL "http://www.gnu.org/" "GNU Project" " of the"
.URL "http://www.fsf.org/" "Free Software Foundation" .
上記の例において、 groff を使って表示しようとした場合には、 www.tmac マクロパッ
ケージの URL マクロの定義の方が ローカルで行われた定義よりも優先される。
他にもいくつかのリンク用のマクロが用意されている。詳しくは groff_www(7) を参照のこと。
その他のマクロ
.DT タブをデフォルトのタブ値 (0.5 インチごと) にリセットする。 改行はしない。
.PD d パラグラフ間の間隔を引き数にセットする (省略されると d=0.4v となる)。
.SS t サブヘッダ t (.SH のようなものだが、サブセクションのために用いる)。
定義済みの文字列
man パッケージには、以下のような定義済みの文字列がある:
\*R 登録シンボル: ®
\*S デフォルトフォントサイズを変更する
\*(Tm 商標シンボル: ™
\*(lq 左に傾いたダブルクォート: “
\*(rq 右に傾いたダブルクォート: ”
安全なサブセット
技術的には man は troff のマクロパッケージだが、実際には多数の別のツールが man ページの
ファイルを処理しており、それらは troff の全ての機能を 実装していないこともある。したがっ
て、他のツールでも正しく処理できるように、 troff のあまり一般的でない機能は、可能ならば用
いないのが望ましい。 様々な troff プリプロセッサ も用いないほうが良いだろう (やむを得ない
場合は tbl(1) は用いても良い。しかし 2 列の表なら、代わりに IP や TP コマンドを用いてみよ
う)。 計算機能も用いない方が良いだろう。他のツールのほとんどはこれらを処理できない。 他の
フォーマットに変換が容易な、単純なコマンドを使うようにしよう。 以下の troff コマンド
は、使っても問題ないと考えてよいだろう (多くの場合、変換コマンドによって無視されるかもしれ
ないが)。 \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh,
ps, so, sp, ti, tr
troff のエスケープシーケンスの多くも利用できる (これらのエスケープシーケンスは \ で始ま
る)。 バックスラッシュ文字を通常のテキストとして使いたい場合は \e とする。 利用できる他の
シーケンスには以下のようなものがある (x や xx は任意の文字, N は任意の数字): \', \`, \-,
\., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, \f(xx. グラフィックの描画にはエスケー
プシーケンスは用いないほうが良い。
bp (改頁) にはオプションパラメータを用いないこと。 sp (垂直スペース) には正の値のみを用い
ること。 man や mdoc マクロパッケージにあるマクロと、 名前が同じで機能の異なるマクロを定義
(de) しないこと。そのような再定義は無視される可能性が高い。 正方向へのインデント (in) に
は、負のインデントを対応させること (このマクロの代わりに RS と RE マクロを使った方がよいの
だが)。 条件テスト (if,ie) は状態として 't' または 'n' だけを持つようにすること。 変換
(tr) には無視できるものだけを使うこと。 フォントの変更 (ft と \f エスケープシーケンス) に
は 1, 2, 3, 4, R, I, B, P, CW のみを用いること (ft コマンドの場合はパラメータを指定しなく
てもよい)。
この制限を越えて機能を用いる場合は、いくつかのツールを使って、 その結果を注意してチェック
すること。追加した機能が安全だと 確信したら、この文書の管理者にその安全なコマンドまたは
シーケンスを 教えてほしい。リストに追加する。
ファイル
/usr/share/groff/[*/]tmac/an.tmac
/usr/man/whatis
注意
テキストにはぜひとも完全な URL (または URI) を書くようにすること。 man2html(1) のような
ツールは、これらを自動的にハイパーテキストリンクに変換する。 新たに取り入れられた URL マク
ロを関連情報へのリンクに用いても良い。 URL を書く場合は、 例えば
⟨http://www.kernelnotes.org⟩ のように完全な形式で書き、 ツールによる URL 自動検知ができる
ようにすること。
これらのファイルを処理するツールは、ファイルをオープンして 最初の空白以外の文字を調べ
る。行の先頭にピリオド (.) またはシングルクォート (') があると、これは troff ベースの
ファイル (man や mdoc) であるとみなす。左角括弧 (<) は SGML/XML ベースのファイル (HTML や
Docbook) であるとみなす。 それ以外は単純な ASCII テキスト ("catman" の結果など) とみなす。
多くの man ページは、最初の行が ´\" とスペースで始まっており、 そこにはそのページが処理さ
れるべきプリプロセスを表す文字が書いてある。 troff 以外の変換プログラムへの移植性のため、
tbl(1) や、 Linux が自動的に検知できるもの以外は使わないようにすることを勧める。 しか
し、この情報を記述して、書いたページが他の (より低機能な) システムでも 扱えるようにしたい
場合もあるかも知れない。 以下にこれらの文字によって起動されるプリプロセッサの定義を示す:
e eqn(1)
g grap(1)
p pic(1)
r refer(1)
t tbl(1)
v vgrind(1)
バグ
mdoc や DocBook に比べると、 マクロの多くは書式 (フォントタイプやスペーシングなど) に関す
るものであり、 意味上のもの (このテキストは他のページへの参照である、など) ではない (HTML
ですら意味的なマーキングに思える)。 このため、 man フォーマットを他のメディアへ変換した
り、 フォーマットを他のメディアで有効なものにしたり、 相互参照を自動的に挿入したりすること
が困難になっている。 上に挙げたような安全なサブセットを守れば、 将来別のリファレンスページ
フォーマットへ変換する作業が簡単になるだろう。
Sun のマクロである TX は定義されていない。
関連項目
apropos(1), groff(1), lexgrog(1), man(1), man2html(1), whatis(1), groff_man(7),
groff_www(7), man-pages(7), mdoc(7), mdoc.samples(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.54 の一部 である。プロジェクト
の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。