Provided by: manpages-ja_0.5.0.0.20221215+dfsg-1_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 スモール (頭字語などに用いる)
Traditionally, each command can have up to six arguments, but the GNU implementation removes this
limitation (you might still want to limit yourself to 6 arguments for portability's sake). Arguments are
delimited by spaces. Double quotes can be used to specify an argument which contains spaces. For the
macros that produce alternating type faces, the arguments will be printed next to each other without
intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of
punctuation in Roman. If no arguments are given, the command is applied to the following line of text.
その他のマクロや文字列
Below are other relevant macros and predefined strings. Unless noted otherwise, all macros cause a break
(end the current line of text). Many of these macros set or use the "prevailing indent." The "prevailing
indent" value is set by any macro with the parameter i below; macros may omit i in which case the current
prevailing indent will be used. As a result, successive indented paragraphs can use the same indent
without respecifying the indent value. A normal (nonindented) paragraph resets the prevailing indent
value to its default value (0.5 inches). By default, a given indent is measured in ens; try to use ens
or ems as units for indents, since these will automatically adjust to font size changes. The other key
macro definitions are:
通常の段落
.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 コマンドと似たものになる。
ハイパーテキストリンク用のマクロ
.UR url
Insert a hypertext link to the URI (URL) url, with all text up to the following .UE macro as the
link text.
.UE [ trailer ]
Terminate the link text of the preceding .UR macro, with the optional trailer (if present, usually
a closing parenthesis and/or end-of-sentence punctuation) immediately following. For non-HTML
output devices (e.g., man -Tutf8), the link text is followed by the URL in angle brackets; if
there is no link text, the URL is printed as its own link text, surrounded by angle brackets.
(Angle brackets may not be available on all output devices.) For the HTML output device, the link
text is hyperlinked to the URL; if there is no link text, the URL is printed as its own link text.
These macros have been supported since GNU Troff 1.20 (2009-01-05) and Heirloom Doctools Troff since
160217 (2016-02-17).
その他のマクロ
.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
You may also use many troff escape sequences (those sequences beginning with \). When you need to
include the backslash character as normal text, use \e. Other sequences you may use, where x or xx are
any characters and N is any digit, include: \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx,
\fx, and \f(xx. Avoid using the escape sequences for drawing graphics.
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
注意
By all means include full URLs (or URIs) in the text itself; some tools such as man2html(1) can automatically turn them into hypertext links. You can also use the UR and UE macros to identify links to related information. If you include URLs, use the full URL (e.g., ⟨http://www.kernel.org⟩) to ensure that tools can automatically find the URLs. Tools processing these files should open the file and examine the first nonwhitespace character. A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based file (such as HTML or Docbook). Anything else suggests simple ASCII text (e.g., a "catman" result). Many man pages begin with '\" followed by a space and a list of characters, indicating how the page is to be preprocessed. For portability's sake to non-troff translators we recommend that you avoid using anything other than tbl(1), and Linux can detect that automatically. However, you might want to include this information so your man page can be handled by other (less capable) systems. Here are the definitions of the preprocessors invoked by these characters: 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)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告
に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。