draft/man7/man.7

   1 .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
   2 .\" (faith@cs.unc.edu and dwheeler@ida.org)
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" Modified Sat Jun  8 00:39:52 1996 by aeb
  28 .\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org)
  29 .\" Modified Thu Jul 15 12:43:28 1999 by aeb
  30 .\" Modified Sun Jan  6 18:26:25 2002 by Martin Schulze <joey@infodrom.org>
  31 .\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org>
  32 .\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7.
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" This file was generated with po4a. Translate the source file.
  37 .\"
  38 .\"*******************************************************************
  39 .TH MAN 7 2012\-08\-05 Linux "Linux Programmer's Manual"
  40 .SH 名前
  41 man \- man ページを整形するマクロ
  42 .SH 書式
  43 \fBgroff \-Tascii \-man\fP \fIfile\fP \&...
  44 .LP
  45 \fBgroff \-Tps \-man\fP \fIfile\fP \&...
  46 .LP
  47 \fBman\fP [\fIsection\fP] \fItitle\fP
  48 .SH 説明
  49 このマニュアルページでは、 \fBgroff an.tmac\fP のマクロパッケージ (\fBman\fP マクロパッケージとも呼ばれることも多い)
  50 について説明する。 このマクロパッケージは、 Linux の man ページを書いたり移植したりするときに、 開発者が用いるものである。
  51 このマクロパッケージはバージョン間での互換性が高く、 man page の移植にあたっては大きな問題はないだろう (但し、NET\-2 BSD
  52 release は例外である。 こちらでは mdoc と呼ばれる全く異なるマクロパッケージが使用されている。 \fBmdoc\fP(7)  を参照)。
  53 .PP
  54 NET\-2 BSD の man ページも、 \fBgroff\fP のオプションとして \fB\-man\fP の代わりに \fB\-mdoc\fP
  55 を指定するだけで、利用することができる。 \fB\-mandoc\fP オプションを使えばどのマクロパッケージが用いられているか
  56 自動的に検出できるので、このオプションを使うのがお薦めである。
  57 .PP
  58 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事については \fBman\-pages\fP(7)  を参照。
  59 .SS タイトル行
  60 man ページの (コメント行を除く) 最初のコマンドは、 以下のようにする必要がある。 コメント行とは \fB.\e"\fP で始まる行のことである。
  61 .RS
  62 .sp
  63 \fB\&.TH\fP \fItitle section date source manual\fP
  64 .sp
  65 .RE
  66 \fBTH\fP に渡す引き数の詳細については \fBman\-pages\fP(7)  を参照。
  67 .PP
  68 なお BSD の mdoc フォーマットのページは \fBTH\fP コマンドではなく \fBDd\fP コマンドから始まる。
  69 .SS セクション
  70 .\" The following doesn't seem to be required (see Debian bug 411303),
  71 .\" If the name contains spaces and appears
  72 .\" on the same line as
  73 .\" .BR \&.SH ,
  74 .\" then place the heading in double quotes.
  75 セクションは \fB\&.SH\fP で始まり、見出し名がそれに続く。
  76
  77 NAME (名前) という見出しだけは必ず置かないといけない。 この見出しは一番最初のセクションにすべきで、見出しの
  78 次の行にはプログラムの説明を一行で書く。
  79 .RS
  80 .sp
  81 \&.SH NAME
  82 .br
  83 item \e\- description
  84 .sp
  85 .RE
  86 このフォーマットに従い、コマンド名に続くシングルダッシュ (\-) の前には必ず
  87 バックスラッシュを置くこと。 この文法は、 \fBmabdb\fP(8) プログラムが
  88 \fBwhatis\fP(1) や \fBapropos\fP(1) コマンド用の短い説明のデータベースを
  89 生成する際に利用される。
  90 .PP
  91 マニュアルページに登場する可能性のあるこれ以外のセクションのリストに ついては \fBman\-pages\fP(7)  を参照。
  92 .SS フォント
  93 タイプフェイスを選択するコマンドは以下のように指定する:
  94 .TP  4
  95 \fB\&.B\fP
  96 ボールド。
  97 .TP
  98 \fB\&.BI\fP
  99 ボールドとイタリックとを交互に (特に関数指定に便利)。
 100 .TP
 101 \fB\&.BR\fP
 102 ボールドとローマンとを交互に (特に他のマニュアルページを参照するときに便利)。
 103 .TP
 104 \fB\&.I\fP
 105 イタリック。
 106 .TP
 107 \fB\&.IB\fP
 108 イタリックとボールドとを交互に。
 109 .TP
 110 \fB\&.IR\fP
 111 イタリックとローマンとを交互に。
 112 .TP
 113 \fB\&.RB\fP
 114 ローマンとボールドとを交互に。
 115 .TP
 116 \fB\&.RI\fP
 117 ローマンとイタリックとを交互に。
 118 .TP
 119 \fB\&.SB\fP
 120 スモールとボールドを交互に。
 121 .TP
 122 \fB\&.SM\fP
 123 スモール (頭字語などに用いる)
 124 .LP
 125 慣例としては、各コマンドは 6 つまでの引き数を持つ事が可能だが、 GNU の実装では制限はないようだ (しかし移植性を保持するためには 引き数は 6
 126 までに限っておくのが良いだろう)。 引き数はスペースで区切られる。 スペースを含んだ引き数を与えるには、ダブルクォートで囲えばよい。
 127 すべての引き数はスペースを取り除いて並べられるので、 \fB\&.BR\fP コマンドを使えば、単語はボールドで、句読点をローマンで表すことができる。
 128 引き数が全く与えられなければ、 そのコマンドは次の行のテキストに適用される。
 129 .SS その他のマクロや文字列
 130 .PP
 131 以下に、他のマクロや定義済みの文字列を示す。 特に記述がない限り、マクロを使うと改行が行われる (テキストの現在の行を終了する)。 多くのマクロは
 132 「優先インデント (prevailing indent)」を設定したり、使用する。 優先インデントの値は、どのマクロからもパラメータ \fIi\fP
 133 によって指定できる (以下に示す)。 マクロでは \fIi\fP を省略することもでき、その場合は現在の優先インデントの値が用いられる。
 134 これにより結果として、インデントされた段落が連続している場合、 インデントの値を再指定しなくてもインデント量を同じにすることができる。 通常の
 135 (インデントされていない) 段落が登場すると、 優先インデントの値はデフォルトの値 (0.5 インチ) にリセットされる。
 136 デフォルトでは、与えたインデントの値は ens 単位である。 インデントの単位には ens や ems を用いるとよい。これらの単位は
 137 フォントサイズが変更されると自動的に調整されるからである。 他の重要なマクロ定義は以下の通り:
 138 .SS 通常の段落
 139 .TP  9m
 140 \fB\&.LP\fP
 141 \fB\&.PP\fP と同じ (新たな段落の開始)。
 142 .TP
 143 \fB\&.P\fP
 144 \fB\&.PP\fP と同じ (新たな段落の開始)。
 145 .TP
 146 \fB\&.PP\fP
 147 新しい段落を開始し、インデントをリセットする。
 148 .SS 相対マージンインデント
 149 .TP  9m
 150 \fB\&.RS\fP\fI i\fP
 151 相対マージンインデント (relative margin indent) を開始する。 左マージンを \fIi\fP だけ右に移動する (\fIi\fP
 152 が省略されると優先インデントの値が用いられる)。 新たな優先インデントは 0.5 インチにセットされる。 結果として、以下の段落は対応する
 153 \fB\&.RE\fP が現れるまでインデントされる。
 154 .TP
 155 \fB\&.RE\fP
 156 相対マージンインデントを終了し、 優先インデントの値を元に戻す。
 157 .SS 段落をインデントするマクロ
 158 .TP  9m
 159 \fB\&.HP\fP\fI i\fP
 160 ぶらさがりインデントの段落を開始する (段落の先頭行は通常の段落の左マージンとなり、 段落の残りの行はインデントされる)。
 161 .TP
 162 \fB\&.IP\fP\fI x i\fP
 163 インデントされた段落。オプションとしてぶらさがりタグをとる。 タグ \fIx\fP が省略されると、以下の段落すべてが \fIi\fP でインデントされる。タグ
 164 \fIx\fP が与えられると、タグはインデントされた段落の前にぶら下げられる (\fB\&.TP\fP
 165 とちょうど同じ。ただしタグを次の行に書く代わりにコマンドに指定する)。 タグが長すぎる場合には、タグに続くテキストは次の行に移動する
 166 (テキストが失われたり混ざったりすることはない)。 箇条書きをするには、 \e(bu (点) あるいは \e(em (ダッシュ)
 167 をタグにしてこのマクロを用いるとよい。番号付きで箇条書きをする場合は、 数字または文字にピリオドを付けたものをタグにすればよい。
 168 こうすれば他のフォーマットへの変換が簡単になる。
 169 .TP
 170 \fB\&.TP\fP\fI i\fP
 171 ぶらさがりタグの段落を開始する。タグは次の行に指定する。 結果は \fB\&.IP\fP コマンドと似たものになる。
 172 .SS ハイパーテキストリンク用のマクロ
 173 (\fBgroff\fP だけでサポートされている機能)  ハイパーテキストリンク用のマクロを使用するためには、 \fBwww.tmac\fP
 174 マクロパッケージをロードする必要がある。 ロードを行うには \fB.mso www.tmac\fP リクエストを使用する。
 175 .TP  9m
 176 \fB\&.URL\fP\fI link url trailer\fP
 177 .\" The following is a kludge to get a paragraph into the listing.
 178 URI (URL)  \fIurl\fP へのハイパーテキストリンクを挿入する。 \fIlink\fP はリンク名のテキストであり、 \fItrailer\fP
 179 の内容はリンクの直後に表示される。 HTML を生成する時に、このマクロは \fB<A
 180 HREF="\fP\fIurl\fP\fB">\fP\fIlink\fP\fB</A>\fP\fItrailer\fP という HTML コマンドに変換される。
 181 .TP
 182 \fB\& \&\fR
 183 .\" The following is a kludge to get a paragraph into the listing.
 184 このマクロや他の関連マクロは新しく、 多くのツールはこれらに対しては何もしないであろう。 (troff を含めた)
 185 多くのツールは未定義のマクロを単に無視するだけ (あるいは最悪でもマクロをテキストとして挿入するだけ)  なので、これらを書いても危険はない。
 186 .TP
 187 \fB\& \&\fR
 188 .\" The following is a kludge to get a paragraph into the listing.
 189 マニュアルページ内で自分で \fBURL\fP マクロを定義して、 \fBgroff\fP 以外の roff ビューアでも表示されるようにするのもいいだろう。
 190 こうすることで、URL も、リンク用のテキストも、(もしあれば) それに続く テキストも、表示できるようになる。
 191 .TP
 192 \fB\& \&\fR
 193 以下に例を挙げる:
 194 .RS 1.5i
 195 \&.de URL
 196 .br
 197 \e\e$2 \e(laURL: \e\e$1 \e(ra\e\e$3
 198 .br
 199 \&..
 200 .br
 201 \&.if \en[.g] .mso www.tmac
 202 .br
 203 \&.TH \fI...\fP
 204 .br
 205 \fI(later in the page)\fP
 206 .br
 207 This software comes from the
 208 .br
 209 \&.URL "http://www.gnu.org/" "GNU Project" " of the"
 210 .br
 211 \&.URL "http://www.fsf.org/" "Free Software Foundation" .
 212 .RE
 213 .\" The following is a kludge to get a paragraph into the listing.
 214 .TP
 215 \fB\& \&\fR
 216 上記の例において、 \fBgroff\fP を使って表示しようとした場合には、 \fBwww.tmac\fP マクロパッケージの URL マクロの定義の方が
 217 ローカルで行われた定義よりも優先される。
 218 .PP
 219 他にもいくつかのリンク用のマクロが用意されている。詳しくは \fBgroff_www\fP(7) を参照のこと。
 220 .SS その他のマクロ
 221 .TP  9m
 222 \fB\&.DT\fP
 223 タブをデフォルトのタブ値 (0.5 インチごと) にリセットする。 改行はしない。
 224 .TP
 225 \fB\&.PD\fP\fI d\fP
 226 パラグラフ間の間隔を引き数にセットする (省略されると d=0.4v となる)。
 227 .TP
 228 \fB\&.SS\fP\fI t\fP
 229 サブヘッダ \fIt\fP (\fB\&.SH\fP のようなものだが、サブセクションのために用いる)。
 230 .SS 定義済みの文字列
 231 \fBman\fP パッケージには、以下のような定義済みの文字列がある:
 232 .IP \e*R
 233 登録シンボル: \*R
 234 .IP \e*S
 235 デフォルトフォントサイズを変更する
 236 .IP \e*(Tm
 237 商標シンボル: \*(Tm
 238 .IP \e*(lq
 239 左に傾いたダブルクォート: \*(lq
 240 .IP \e*(rq
 241 右に傾いたダブルクォート: \*(rq
 242 .SS 安全なサブセット
 243 技術的には \fBman\fP は troff のマクロパッケージだが、実際には多数の別のツールが man ページのファイルを処理しており、それらは
 244 troff の全ての機能を 実装していないこともある。したがって、他のツールでも正しく処理できるように、 troff
 245 のあまり一般的でない機能は、可能ならば用いないのが望ましい。 様々な troff プリプロセッサ も用いないほうが良いだろう (やむを得ない場合は
 246 \fBtbl\fP(1)  は用いても良い。しかし 2 列の表なら、代わりに \fBIP\fP や \fBTP\fP コマンドを用いてみよう)。
 247 計算機能も用いない方が良いだろう。他のツールのほとんどはこれらを処理できない。 他のフォーマットに変換が容易な、単純なコマンドを使うようにしよう。
 248 以下の troff コマンドは、使っても問題ないと考えてよいだろう (多くの場合、変換コマンドによって無視されるかもしれないが)。 \fB\e"\fP,
 249 \&\fB.\fP, \fBad\fP, \fBbp\fP, \fBbr\fP, \fBce\fP, \fBde\fP, \fBds\fP, \fBel\fP, \fBie\fP, \fBif\fP, \fBfi\fP,
 250 \fBft\fP, \fBhy\fP, \fBig\fP, \fBin\fP, \fBna\fP, \fBne\fP, \fBnf\fP, \fBnh\fP, \fBps\fP, \fBso\fP, \fBsp\fP,
 251 \fBti\fP, \fBtr\fP
 252 .PP
 253 troff のエスケープシーケンスの多くも利用できる (これらのエスケープシーケンスは \e で始まる)。
 254 バックスラッシュ文字を通常のテキストとして使いたい場合は \ee とする。 利用できる他のシーケンスには以下のようなものがある (x や xx
 255 は任意の文字, N は任意の数字): \fB\e'\fP, \fB\e`\fP, \fB\e\-\fP, \fB\e.\fP, \fB\e"\fP, \fB\e%\fP, \fB\e*x\fP,
 256 \fB\e*(xx\fP, \fB\e(xx\fP, \fB\e$N\fP, \fB\enx\fP, \fB\en(xx\fP, \fB\efx\fP, \fB\ef(xx\fP.
 257 グラフィックの描画にはエスケープシーケンスは用いないほうが良い。
 258 .PP
 259 \fBbp\fP (改頁) にはオプションパラメータを用いないこと。 \fBsp\fP (垂直スペース) には正の値のみを用いること。 man や mdoc
 260 マクロパッケージにあるマクロと、 名前が同じで機能の異なるマクロを定義 (\fBde\fP)  しないこと。そのような再定義は無視される可能性が高い。
 261 正方向へのインデント (\fBin\fP)  には、負のインデントを対応させること (このマクロの代わりに \fBRS\fP と \fBRE\fP
 262 マクロを使った方がよいのだが)。 条件テスト (\fBif\fP,\fBie\fP)  は状態として \(aqt\(aq または \(aqn\(aq
 263 だけを持つようにすること。 変換 (\fBtr\fP)  には無視できるものだけを使うこと。 フォントの変更 (\fBft\fP と \fB\ef\fP
 264 エスケープシーケンス) には 1, 2, 3, 4, R, I, B, P, CW のみを用いること (ft
 265 コマンドの場合はパラメータを指定しなくてもよい)。
 266 .PP
 267 この制限を越えて機能を用いる場合は、いくつかのツールを使って、 その結果を注意してチェックすること。追加した機能が安全だと
 268 確信したら、この文書の管理者にその安全なコマンドまたはシーケンスを 教えてほしい。リストに追加する。
 269 .SH ファイル
 270 \fI/usr/share/groff/\fP[*/]\fItmac/an.tmac\fP
 271 .br
 272 \fI/usr/man/whatis\fP
 273 .SH 注意
 274 .PP
 275 テキストにはぜひとも完全な URL (または URI) を書くようにすること。 \fBman2html\fP(1)
 276 のようなツールは、これらを自動的にハイパーテキストリンクに変換する。 新たに取り入れられた \fBURL\fP マクロを関連情報へのリンクに用いても良い。
 277 URL を書く場合は、 例えば
 278 .UR http://www.kernelnotes.org
 279 .UE
 280 のように完全な形式で書き、
 281 ツールによる URL 自動検知ができるようにすること。
 282 .PP
 283 これらのファイルを処理するツールは、ファイルをオープンして 最初の空白以外の文字を調べる。行の先頭にピリオド (.)  またはシングルクォート (')
 284 があると、これは troff ベースの ファイル (man や mdoc) であるとみなす。左角括弧 (<) は SGML/XML
 285 ベースのファイル (HTML や Docbook) であるとみなす。 それ以外は単純な ASCII テキスト ("catman" の結果など)
 286 とみなす。
 287 .PP
 288 多くの man ページは、最初の行が \fB\'\e"\fP とスペースで始まっており、
 289 そこにはそのページが処理されるべきプリプロセスを表す文字が書いてある。 troff 以外の変換プログラムへの移植性のため、 \fBtbl\fP(1)  や、
 290 Linux が自動的に検知できるもの以外は使わないようにすることを勧める。 しかし、この情報を記述して、書いたページが他の (より低機能な)
 291 システムでも 扱えるようにしたい場合もあるかも知れない。 以下にこれらの文字によって起動されるプリプロセッサの定義を示す:
 292 .TP  3
 293 \fBe\fP
 294 eqn(1)
 295 .TP
 296 \fBg\fP
 297 grap(1)
 298 .TP
 299 \fBp\fP
 300 pic(1)
 301 .TP
 302 \fBr\fP
 303 refer(1)
 304 .TP
 305 \fBt\fP
 306 tbl(1)
 307 .TP
 308 \fBv\fP
 309 vgrind(1)
 310 .SH バグ
 311 .PP
 312 mdoc や DocBook に比べると、 マクロの多くは書式 (フォントタイプやスペーシングなど) に関するものであり、 意味上のもの
 313 (このテキストは他のページへの参照である、など) ではない (HTML ですら意味的なマーキングに思える)。 このため、 \fBman\fP
 314 フォーマットを他のメディアへ変換したり、 フォーマットを他のメディアで有効なものにしたり、 相互参照を自動的に挿入したりすることが困難になっている。
 315 上に挙げたような安全なサブセットを守れば、 将来別のリファレンスページフォーマットへ変換する作業が簡単になるだろう。
 316 .LP
 317 .\" .SH AUTHORS
 318 .\" .IP \(em 3m
 319 .\" James Clark (jjc@jclark.com) wrote the implementation of the macro package.
 320 .\" .IP \(em
 321 .\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of
 322 .\" this manual page.
 323 .\" .IP \(em
 324 .\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO
 325 .\" (which influenced this manual page).
 326 .\" .IP \(em
 327 .\" David A. Wheeler (dwheeler@ida.org) heavily modified this
 328 .\" manual page, such as adding detailed information on sections and macros.
 329 Sun のマクロである \fBTX\fP は定義されていない。
 330 .SH 関連項目
 331 \fBapropos\fP(1), \fBgroff\fP(1), \fBlexgrog\fP(1), \fBman\fP(1), \fBman2html\fP(1),
 332 \fBwhatis\fP(1), \fBgroff_man\fP(7), \fBgroff_www\fP(7), \fBman\-pages\fP(7), \fBmdoc\fP(7),
 333 \fBmdoc.samples\fP(7)
 334 .SH この文書について
 335 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 336 である。プロジェクトの説明とバグ報告に関する情報は
 337 http://www.kernel.org/doc/man\-pages/ に書かれている。