名称
groff_man -
マニュアルページ生成サポート用
groff `man' マクロ
書式
groff -man [ options... ] [ files... ]
groff -m man [ options... ] [ files...
]
解説
groff
でマニュアルページを生成するのに使用される
man マクロは、James Clark
が書きました。
このドキュメントは、パッケージ中の各マクロの使い方を、短くまとめたものです。
オプション
man
マクロは、次のようなコマンドラインオプションを理解します
(レジスタをいくつか定義します)。
- -rcR=1
- 本オプション (nroff
モードではデフォルト)
は、
複数ページの代りに、長い単一ページを出力します。
無効にするには、
-rcR=0
としてください。
- -rC1
- コマンドラインに複数のマニュアルページを与えた場合、
それぞれのページ番号が 1
から始まるのではなく、連続した番号に
なります。
- -rD1
- 両面印字にします。
偶数ページと奇数ページのフッタは、異なった整形が成されます。
- -rPnnn
- ページの数え始めを 1
ではなく nnn
からにします。
- -rSxx
- ベースドキュメントフォントサイズを
10 ポイントではなく
xx ポイントにします
(xx には 10, 11, 12
のいずれかが使用できます)。
- -rXnnn
- ページ nnn
の後のページを nnna,
nnnb, nnnc
などというように数えます。例えば、`-rX2'
というオプションの場合、
ページを 1, 2, 2a, 2b, 2c
というように割り振ります。
使用法
このセクションは、マニュアルページ用に使用可能なマクロについて
述べています。さらにカスタマイズしたい場合は、
man.local
ファイル中に追加のマクロおよびリクエストを置いてください。
このファイルは man
の直後にロードされます。
- .TH title section [extra1]
[extra2] [extra3]
- このマニュアルページのタイトルを
title
に、セクションを
section
に設定します。セクションは、
1 から 8
までの値をとらなくてはなりません。
section
値には、後ろに文字列を置くこともできます。例えば、
`.pm'
とすると、マニュアルページの特定のサブセクションを
示します。 title と
section
は、ともにヘッダ行の左端と右端に置かれます
(括弧でくくられた
section が title
の直後に付きます)。
extra1
は、フッタ行の中央に置かれます。
extra2
は、フッタ行の左に置かれます
(両面印字がアクティブになっている場合、偶数ページには
左に、奇数ページには右に、置かれます)。
extra3
はヘッダ行の中央に置かれます。
- HTML
出力用には、ヘッダおよびフッタは完全に取り除かれます。
- さらに、このマクロは改ページします。新しい行番号は、再度 1
に なります
(コマンドラインで `-rC1'
オプションが指定されている場合を
除きます)。この機能は、複数のマニュアルページを整形する
場合のためだけにあります。マニュアルページが
1 つの場合、 TH
は、ファイルの先頭において、まさに
1
つだけ存在すべきです。
- .SH [text for a heading]
- 番号づけをしないセクション用の見出しを設定します。
これは左詰めになります。
SH に続いたテキスト
( SH
に引数がない場合は次の行のテキスト)
は、行末までのものがすべてボールド体で、
そしてベースドキュメントサイズよりも
1
だけ大きなフォントサイズで
表示されます 。
さらに、テキストの左側の余白はデフォルト値に戻されます。
- .SS [text for a heading]
- 番号づけしないセクションの
2
番目の見出しを設定します。
SS に続いたテキスト
( SS
に引数がない場合は次の行のテキスト)
は、行末までのものがすべてボールド体で、
そしてベースドキュメントサイズと同じ大きさのフォントで表示されます。
さらに、テキストの左側の余白はデフォルト値に戻されます。
- .TP [nnn]
- インデントされた、ラベルつきの段落を設定します。
インデント幅は、引数が与えられていれば
nnn に設定されます
(省略されていれば、デフォルトの単位は
`n'
です)。引数が与えられていなければ、インデント幅は
デフォルト値に設定されます。
このマクロの後に続いたテキストの
1 行目は、
左詰めに表示する文字列として解釈され、
ラベルとして使用するのに適切なものとなります。
これは段落の一部であるとは解釈はされませんので、
引き続く入力行のテキストで
1
行目を満たそうとはしません。
それでも、ラベルがインデント幅ほど広がっていない場合には、
同じ行から段落が始まり
(ただし、インデントはされます)、次の
行へと続いていきます。
ラベルがインデント幅よりも広い場合は、段落の説明部分は
ラベルの次の行から始まり、すべてインデントされます。
ラベルのフォントの形もサイズもデフォルト値には設定されない
ことに注意してください。これに対して、残りのテキストは
デフォルトのフォント設定になります。
TP
マクロは、あなたが今ちょうど読んでいるこの解説に使用されている
マクロです。
- .LP
- .PP
- .P
- これらのマクロは、共通の別名です。
これらのうちのどれを使用しても現在の位置で行を打ち切ります。
そして、その後に PD
マクロで指定した量だけ垂直方向にスペースを置きます。
フォントのサイズおよび形はデフォルト値に戻されます
(10pt ローマン体)。
最後に、現在の左側の余白の量を復元します。
- .IP [designator] [nnn]
- インデントされた段落を設定します。その際、
designator
を段落の始まりに印をつけるためのタグとして使用します。
インデント幅は、引数が与えられている場合は
nnn に設定されます
(デフォルトの単位は
`n' です)。
引数が与えられていない場合は、デフォルトのインデント幅が
使用されます。
この段落
(ただし、指示子 (designator)
を含まず) の
フォントサイズおよびフェースはデフォルト値に戻されます。
特定のインデントをするが指示子をつけない段落を開始するには、
第 2 引数に `""'
(ダブルクォート 2 つ)
を使用してください。
- 例えば次の段落は、`.IP \(bu 4'
を用いて、すべて
指示子として中点をつけて設定されます:
- IP
は、リストを整形するために
man で使用される 3
つのマクロのうちの 1
つです。
- HP
は、また別のマクロです。
このマクロは、左側にぶら下げインデントされた段落を生成します。
- TP
は、また別のマクロです。
このマクロは、インデントされないラベルを生成し、その後に
インデントされた段落が続きます。
- .HP [nnn]
- 左側にぶら下げインデントされた段落を設定します。
引数が与えられている場合、インデント幅は
nnn に設定されます
(デフォルトの単位は
`n' です)。
引数が与えられていない場合、デフォルトのインデント幅が
使用されます。
フォントサイズおよびフェースはデフォルト値に戻されます。
次の段落は、インデント幅を 4
に設定されているときの
このマクロの効果を示したものです:
この段落は、 HP
マクロを実行したあとの段落です。
見ての通り、このマクロは、最初の行を除いた行すべてが
インデントされた段落を生成しています。
- .RS [nnn]
- このマクロは、値が与えられていれば
(デフォルト単位は `n'
です)
その値だけ左側の余白を右に移動します。
値が与えられていなければ、デフォルトのインデント幅が
使用されます。 RS
マクロの呼び出しは入れ子にできます。
- .RE [nnn]
- このマクロは、左側の余白を
nnn
レベルまで戻します。引数が与えられていなければ、
このマクロはレベルを
1 つだけ戻します。
第 1 レベル
(すなわち、まだ RS
を呼び出していない)
は番号 1
を持っており、 RS
マクロを呼び出すごとにレベルが 1
ずつ増加します。
まとめると、次のマクロは、垂直方向にスペースを入れた
行の折り返しを行います
(スペースの量は PD
マクロを使用すると変更できます):
SH, SS, TP, LP (PP, P), IP,
HP 。 マクロ RS
および RE
も行を折り返しますが、垂直方向にスペースを入れません。
フォントを設定するためのマクロ
標準フォントはローマン体です。そして、デフォルトのテキストサイズは
10 ポイントです。
- .SM [text]
- 同じ行にあるテキストあるいは次の行にあるテキストが、
デフォルトのフォントよりも
1
ポイントだけ小さいフォントで
表示されるようになります。
- .SB [text]
- 同じ行にあるテキストあるいは次の行にあるテキストが、
ボールド体のフォントで、そしてデフォルトのフォントよりも
1
ポイントだけ小さいフォントで表示されるようになります。
- .BI text
- 同じ行にあるテキストが、ボールド体とイタリック体を
交互に使って表示されるようになります。
テキストはマクロ呼び出しと同じ行にあることが必要です。
したがって、
- .BI this "word and" that
という行は、`this' と
`that'
がボールド体で表示され、
それに対して `word and'
の部分はイタリック体で
表示されます。
- .IB text
- テキストが、イタリック体とボールド体を交互に使って
表示されるようになります。テキストはマクロ呼び出しと
同じ行にあることが必要です。
- .RI text
- マクロ呼び出しと同じ行にあるテキストが、ローマン体と
イタリック体を交互に使って表示されるようになります。
テキストは、マクロ呼び出しと同じ行にあることが必要です。
- .IR text
- マクロ呼び出しと同じ行にあるテキストが、イタリック体と
ローマン体を交互に使って表示されるようになります。
テキストは、マクロ呼び出しと同じ行にあることが必要です。
- .BR text
- マクロ呼び出しと同じ行にあるテキストが、ボールド体と
ローマン体を交互に使って表示されるようになります。
テキストは、マクロ呼び出しと同じ行にあることが必要です。
- .RB text
- マクロ呼び出しと同じ行にあるテキストが、ローマン体と
ボールド体を交互に使って表示されるようになります。
テキストは、マクロ呼び出しと同じ行にあることが必要です。
- .R [text]
- text
がローマン体フォントで表示されるようになります。
マクロが呼び出された行にテキストがない場合は、次の行の
テキストがローマン体で表示されます。
これが、他のマクロを処理し終わったときに返されるテキストの
デフォルトのフォントです。
- .B [text]
- text
がボールド体で表示されるようになります。
マクロが呼び出された行にテキストがない場合は、次の行の
テキストがボールド体で表示されます。
- .I [text]
- text
がイタリック体で表示されるようになります。
マクロが呼び出された行にテキストがない場合は、次の行の
テキストがイタリック体で表示されます。
その他
grohtml
を除いた出力デバイス用のインデント幅はすべて
7.2n です。 grohtml
の場合はインデントを無視します。
- .DT
- 0.5
インチごとにタブを設定します。
このマクロは常に TH
リクエスト中で呼ばれるため、タブ位置が変更された場合に限って
呼び出すことには意味があります。
- .PD [nnn]
- 新しい段落
(セクション)
の前のスペースを調整します。
オプションの引数は、スペースの量を与えます
(デフォルトの単位は
`v')。
パラメータ無しの場合、この値はデフォルト値に戻されます
(tty デバイスでは 1
行で、それ以外では
0.4v)。
このリクエストは、
SH, SS, TP, LP
(それぞれ PP および
P), IP, HP
マクロに影響を与えます。
次の文字列が定義されています:
- \*S
- デフォルトのフォントサイズに戻します。
- \*R
- 「登録」マークです。
- \*(Tm
- 「商標」マークです。
- \*(lq
- \*(rq
- 左および右クォートです。
これは、それぞれ `\(lq'
と `\(rq' と同じです。
tbl あるいは eqn
のようなプリプロセッサが必要な場合、マニュアルページの
1
行目を次のように見えるようにする例になります:
.\" word
ダブルクォートの後には空白文字
1
つが入ることに注意してください。
word
は、必要なプリプロセッサを表す文字で成り立っています。
`e' は eqn を表し、 `r' は
refer を、そして `t' は
tbl を表します。
最近の man
プログラムの実装では、この
1
行目を読んで自動的に正しい
プリプロセッサを呼び出します。
関連項目
man マクロは、 groff
リクエストの集まりでできていますので、原理的には、
必要がある場合には自己流の
groff
リクエストを作って
man
の機能を追加することができます。
これらのリクエストの完全なリストは
WWW ページ
http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html
から入手できます。
tbl(1), eqn(1), refer(1), man(1)
作者
このマニュアルページは、本来
Debian GNU/Linux システム用に Susan G.
Kleinmann <sgk@debian.org>
が書いたものです。
それを Werner Lemberg <wl@gnu.org>
が修正し、更新しました。
それが今では GNU troff
配布物の一部になっています。