release/man7/mdoc.samples.7

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)mdoc.samples.7      8.2 (Berkeley) 12/30/93
  35 .\"     $Id: mdoc.samples.7,v 1.17 1998/12/03 03:38:45 jkoshy Exp $
  36 .\"
  37 .\" This tutorial sampler invokes every macro in the package several
  38 .\" times and is guaranteed to give a worst case performance
  39 .\" for an already extremely slow package.
  40 .\"
  41 .\" String \*(Pu was not defined, probably means punctuation
  42 .ds Pu [ .,:;()[]?! ]
  43 .\"*******************************************************************
  44 .\"
  45 .\" This file was generated with po4a. Translate the source file.
  46 .\"
  47 .\"*******************************************************************
  48 .Dd December 30, 1993
  49 .Os
  50 .Dt MDOC.SAMPLES 7
  51 .Sh 名前
  52 .Nm mdoc.samples
  53 .Nd
  54 .Nm \-mdoc
  55 を使って
  56 .Bx
  57 マニュアルを書くためのチュートリアルサンプル
  58 .Sh 書式
  59 .Nm man mdoc.samples
  60 .Sh 説明
  61 .Xr troff 1
  62 用の
  63 .Em コンテントベース
  64 でかつ
  65 .Em 領域ベース
  66 なフォーマットパッケージである
  67 .Nm \-mdoc
  68 マクロパッケージを使って
  69 .Bx
  70 マニュアルを書くためのチュートリアルサンプルです。
  71 前身である
  72 .Xr \-man 7
  73 パッケージはフォントの操作や他の写植方法の
  74 詳細は個々の作者に任せたページレイアウトベースのものでした。
  75 .Nm \-mdoc
  76 では、ページレイアウトマクロは
  77 タイトル、セクションのヘッダ、ディスプレイ、リストのマクロからなる
  78 .Em "ページ構造領域"
  79 を形成しています。これらの項目は整形された
  80 ページでのテキストの物理的な位置に影響を持ちます。
  81 ページ構造領域に加え、さらにマニュアル領域および一般テキスト領域
  82 の 2 つの領域があります。
  83 一般テキスト領域はテキストの一部をクォートしたり、
  84 強調するといったような作業を実行するマクロとして定義されています。
  85 マニュアル領域はコマンドやルーチン、それに
  86 .Bx
  87 の関連ファイルを記述するための日常使用されるインフォーマルな言葉の
  88 サブセットであるマクロとして定義されています。
  89 マニュアル領域のマクロはコマンド名、コマンド行の引数とオプション、
  90 関数名、関数のパラメータ、パス名、変数名、他のマニュアルページへの
  91 クロスリファレンスなどを扱います。
  92 これらの領域の項目は作者とマニュアルページの将来のユーザの両者に
  93 とって価値のあるものです。
  94 マニュアル間で一貫性を高めることによって将来のドキュメントツールへの
  95 移行が容易になることが望まれます。
  96 .Pp
  97 マニュアルのエントリは、実際の長さに関わらず、
  98 また男女の区別をするような意図なしで、
  99 .Ux
 100 のマニュアルページを通して、
 101 単純に man ページとして参照されています。
 102 .Sh さあ、始めよう
 103 通常チュートリアルドキュメントは、そこに示された題材をすぐに使いたい時
 104 に読むものですので、このドキュメントのユーザはせっかちな人だと仮定して
 105 います。このドキュメントの残りの部分で説明されている題材は以下のような
 106 構成になっています。
 107 .Bl -enum -offset indent
 108 .It
 109 .Tn "TROFF に特有な表現"
 110 .Bl -tag -width flag -compact -offset indent
 111 .It "マクロの使用方法"
 112 .It "引数に空白文字を指定する"
 113 .It 行末の空白文字 (警告)
 114 .It 特殊文字のエスケープ
 115 .El
 116 .It
 117 .Tn "MAN ページの分析"
 118 .Bl -tag -width flag -compact -offset indent
 119 .It "マニュアルページのテンプレート"
 120 .El
 121 .It
 122 .Tn "タイトルマクロ"
 123 .It
 124 .Tn "マニュアルと一般テキスト領域の紹介"
 125 .Bl -tag -width flag -compact -offset indent
 126 .It "この名前には何が...?"
 127 .It "一般的な構文"
 128 .El
 129 .It
 130 .Tn "マニュアル領域"
 131 .Bl -tag -width flag -compact -offset indent
 132 .It アドレス
 133 .It "作者名"
 134 .It 引数
 135 .It "コンフィギュレーション宣言 (セクション 4 のみ)"
 136 .It "コマンド修飾子"
 137 .It "定義済みの変数"
 138 .It "errno  (セクション 2 のみ)"
 139 .It "環境変数"
 140 .It "関数の引数"
 141 .It "関数の宣言"
 142 .It フラグ
 143 .It "関数 (ライブラリルーチン)"
 144 .It "関数の型"
 145 .\" .It "Header File (including source code)" .
 146 .It "対話的なコマンド"
 147 .It 名前
 148 .It オプション
 149 .It パス名
 150 .It 変数
 151 .It 相互参照
 152 .El
 153 .It
 154 .Tn "一般テキスト領域"
 155 .Bl -tag -width flag -compact -offset indent
 156 .It "AT&T マクロ"
 157 .It "BSD マクロ"
 158 .It "FreeBSD マクロ"
 159 .It "UNIX マクロ"
 160 .It "囲い/クォートマクロ"
 161 .Bl -tag -width flag -compact -offset indent
 162 .It "カギ括弧 <> によるクォート/囲い"
 163 .It "角括弧 [] によるクォート/囲い"
 164 .It "二重引用符マクロ/囲い"
 165 .It "括弧 () によるクォート/囲い"
 166 .It "一重引用符によるクォート/囲い"
 167 .It "プレフィックスマクロ"
 168 .El
 169 .It "no\-op もしくは通常テキストマクロ"
 170 .It "空白なしマクロ"
 171 .It "セクションの相互参照"
 172 .It "相互参照と引用"
 173 .It "返り値 (セクション 2, 3 のみ)"
 174 .It "商標名 (頭字語とタイプ名)"
 175 .It "拡張引数"
 176 .El
 177 .It
 178 .Tn "ページ構造領域"
 179 .Bl -tag -width flag -compact -offset indent
 180 .It "セクションヘッダ"
 181 .It "段落と行スペース"
 182 .It "キープ"
 183 .It "ディスプレイ"
 184 .It "フォントモード (強調、リテラル、およびシンボリック)"
 185 .It "リストと列"
 186 .El
 187 .It
 188 .Tn "定義済みの文字列"
 189 .It
 190 .Tn "診断"
 191 .It
 192 .Tn "GROFF、TROFF、NROFF を使用したフォーマッティング"
 193 .It
 194 .Tn "バグ"
 195 .El
 196 .ne 7
 197 .Sh TROFF に特有な表現
 198 .Nm \-mdoc
 199 パッケージは man ページを記述するプロセスを簡単にすること
 200 を目的としています。
 201 .Nm \-mdoc
 202 を使うために
 203 .Xr troff 1
 204 の
 205 ゴタゴタした詳細を学ぶ必要がないのが理想ですが、いくつか片付けるべき
 206 避けられない制限事項があります。また、このパッケージは高速で
 207 .Em ない
 208 ということも予め警告しておきます。
 209 .Ss マクロの使用方法
 210 .Xr troff 1
 211 のように、マクロは
 212 .Ql \&.
 213 (ドット文字) を行頭に置き、
 214 それに続けて 2 文字からなるマクロの名称を指定することによって呼び出され
 215 ます。引数はマクロの後にスペースで区切って指定することができます。
 216 行頭にドット文字を指定することによって
 217 .Xr troff 1
 218 にそれに続く 2 文
 219 字をマクロ名として解釈するよう指示しています。マクロを起動せずに、ある
 220 文脈の行の先頭に
 221 .Ql \&.
 222 (ドット文字) を置くためには、
 223 .Ql \&.
 224 (ドット) の前にエスケープシーケンス
 225 .Ql \e&
 226 を指定します。
 227 .Ql \e&
 228 は文字通りスペース幅が 0 として解釈され、出力には現れません。
 229 .Pp
 230 一般的に
 231 .Xr troff 1
 232 マクロは引数を 9 つまで取ることができ、
 233 それ以上指定された引数は無視されます。
 234 .Nm \-mdoc
 235 でのほとんどのマクロは 9 つの引数を取ることができ、
 236 限られた場合にのみ引数は次の行に続けて指定することができます
 237 (
 238 .Sx 拡張引数
 239 セクションを参照)。
 240 いくつかのマクロは引用符に囲まれた引数を扱うことができます
 241 (下の
 242 .Sx 引数に空白文字を指定する
 243 セクションを参照)。
 244 .Pp
 245 .Nm \-mdoc
 246 での一般テキスト領域とマニュアル領域のほとんどのマクロは特別であり、
 247 その引数のリストは呼び出し可能なマクロ名として
 248 .Em 解析
 249 されます。
 250 これは一般テキスト領域またはマニュアル領域のマクロ名に一致し、
 251 呼び出し可能であると判断された引数リストの中の引数は、
 252 実行されるか、それが処理される時に呼び出されることを意味しています。
 253 この場合、引数はマクロ名にも関わらず、
 254 .Ql \&.
 255 (ドット) で前置されません。
 256 このようにしてたくさんのマクロを入れ子にすることができます。
 257 例えばオプションマクロ
 258 .Ql \&.Op
 259 はフラグマクロ
 260 .Ql \&Fl
 261 と
 262 引数マクロ
 263 .Ql \&Ar
 264 を
 265 .Em 呼び出して
 266 、
 267 オプションのフラグを引数とともに指定することができます。
 268 .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
 269 .It Op Fl s Ar bytes
 270 は
 271 .Li \&.Op \&Fl s \&Ar bytes
 272 によって生成される
 273 .El
 274 .Pp
 275 2 文字からなる文字列をマクロ名として解釈されないようにするには、
 276 その文字列の前にエスケープシーケンス
 277 .Ql \e&
 278 を指定します。
 279 .Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
 280 .It Op \&Fl s \&Ar bytes
 281 は
 282 .Li \&.Op \e&Fl s \e&Ar bytes
 283 によって生成される
 284 .El
 285 .Pp
 286 ここで文字列
 287 .Ql \&Fl
 288 と
 289 .Ql \&Ar
 290 はマクロとして解釈されていませ
 291 ん。本ドキュメントと関連のクイックリファレンスマニュアル
 292 .Xr mdoc 7
 293 を通して、引数リストが呼び出し可能な引数として解析されるマクロは「解析
 294 される」、引数リストから呼び出されることができるマクロは「呼び出し可能」
 295 と表現します。
 296 .Nm \-mdoc
 297 のほとんどすべてのマクロは解析されるのです
 298 から、これは技術的には
 299 .Em 不謹慎な
 300 ことですが、常にマクロを「呼び出
 301 し可能である」とか「他のマクロを呼び出すことができる」と表現するのは面
 302 倒なことであるため、「解析される」という用語が使われています。
 303 .Ss 引数に空白文字を指定する
 304 ひとつ以上の空白文字を含む文字列をひとつの引数として指定したい場合がよ
 305 くあります。これは 9 個を越える引数を指定できないという制限に対処したり、
 306 引数のリストにある特有な配置をおこなうことが必要なマクロに引数を指定す
 307 るような場合に必要となることがあります。
 308 たとえば、関数マクロ
 309 .Ql \&.Fn
 310 では最初の引数は関数名であり、残りの
 311 引数が関数のパラメータであることが必要です。
 312 .Tn "ANSI C"
 313 の括弧で
 314 囲まれたパラメータリストにおける関数のパラメータの宣言の規定により、
 315 各パラメータは最低でも 2 語の文字列となります。
 316 たとえば
 317 .Fa int foo
 318 のようになります。
 319 .Pp
 320 空白を含む引数を指定するには 2 通りの方法があります。
 321 .Em 実装上の注意 :
 322 解析の前に個々の引数を再割り当てすることによって、
 323 引用符の間に空白を含めて渡すのが最も便利な方法なのですが、
 324 .Tn AT&T
 325 の
 326 .Xr troff
 327 のすべてのマクロを実装するには処理速度およ
 328 びメモリ使用量の点でかなり高価な方法となります。
 329 .Xr groff
 330 では高価な処理にはなりませんが、移植性のため、この方法は
 331 空白を含めることが最も必要である以下のマクロだけに限っています。
 332 .Pp
 333 .Bl -tag -width 4n -offset indent -compact
 334 .It Li \&Cd
 335 コンフィギュレーション宣言 (セクション 4 の
 336 .Sx SYNOPSIS )
 337 .It Li \&Bl
 338 リスト開始 (幅指定用)
 339 .It Li \&Em
 340 テキスト強調
 341 .It Li \&Fn
 342 関数 (セクション 2 と 4)
 343 .It Li \&It
 344 リストの項目
 345 .It Li \&Li
 346 リテラルテキスト
 347 .It Li \&Sy
 348 シンボリックテキスト
 349 .It Li \&%B
 350 書籍のタイトル
 351 .It Li \&%J
 352 定期刊行物のタイトル
 353 .It Li \&%O
 354 参照の追加的な注釈
 355 .It Li \&%R
 356 報告書のタイトル (参照の中で)
 357 .It Li \&%T
 358 書籍や定期刊行物の中の記事のタイトル
 359 .El
 360 .Pp
 361 空白を含む文字列を渡すのに、固定空白、すなわち詰め込まれない
 362 空白文字
 363 .Ql \e\
 364 を使う方法があります。
 365 すなわち、空白の前にエスケープ文字
 366 .Ql \e
 367 を指定する方法です。
 368 この方法はどのマクロでも使うことができますが、1 行を越える長さの
 369 テキストの調整の邪魔になるという副作用があります。
 370 .Xr Troff
 371 では
 372 固定空白は他の印刷可能文字と同様に扱われ、通常期待されるように、
 373 そこで文字列を空白や改行で分けることを行なわなくなります。
 374 この方法は文字列が行の境界をまたがないであろう場合に有用です。
 375 例えば、
 376 .Bl -tag -width "fetch(char *str)" -offset indent
 377 .It Fn fetch char\ *str
 378 は
 379 .Ql \&.Fn fetch char\e *str
 380 によって生成される
 381 .It Fn fetch "char *str"
 382 は
 383 .Ql \&.Fn fetch "\*qchar *str\*q"
 384 でも生成される
 385 .El
 386 .Pp
 387 もし
 388 .Ql \e
 389 や引用符が省かれると、
 390 .Ql \&.Fn
 391 は引数を 3 つ取り、
 392 その結果は以下のようになります。
 393 .Pp
 394 .Dl Fn fetch char *str
 395 .Pp
 396 パラメータのリストが改行の境界をまたぐ場合に何がおこるかについては、
 397 .Sx バグ
 398 のセクションを参照してください。
 399 .Ss 行末の空白文字
 400 .Xr Troff
 401 は行末に空白文字があると混乱してしまうことがあります。
 402 <空白> <行末> の文字シーケンスからすべての
 403 空白文字を取り除くのは良い予防策です。
 404 どうしても行末に空白文字をおく必要性が出てきた場合は、
 405 詰め込まれない空白とエスケープ文字
 406 .Ql \e&
 407 を
 408 使用することによって対応できます。
 409 例えば、
 410 .Ql string\e\ \e&
 411 のようにします。
 412 .Ss 特殊文字のエスケープ
 413 改行
 414 .Ql \en
 415 のような特殊文字は
 416 .Ql \e
 417 を
 418 .Ql \ee
 419 で置き換える
 420 (すなわち
 421 .Ql \een
 422 とする) ことによって、
 423 バックスラッシュを残して扱うことができます。
 424 .Sh MAN ページの分析
 425 man ページの本文はファイル
 426 .Pa /usr/share/misc/mdoc.template
 427 の基本テンプレートを使って容易に作り上げることができます。
 428 .Pa /usr/share/examples/mdoc
 429 にはいくつかのサンプルの man ページが収められています。
 430 .Pp
 431 .Ss マニュアルページのテンプレート
 432 .Bd -literal -offset indent
 433 \&.\e" 以下の項目はすべての man ページで必要な項目です。
 434 \&.Dd 月 日, 年
 435 \&.Os オペレーティングシステム [バージョン/リリース]
 436 \&.Dt ドキュメントタイトル [セクション番号] [ボリューム]
 437 \&.Sh NAME
 438 \&.Nm 名前
 439 \&.Nd 名前の 1 行での説明
 440 \&.Sh SYNOPSIS
 441 \&.Sh DESCRIPTION
 442 \&.\e" 以下の項目については、必要に応じてコメントをはずして
 443 \&.\e" 使用してください。
 444 \&.\e" この次の項目はセクション 2, 3, 9 でのみ必要な、関数の
 445 \&.\e" 戻り値です。
 446 \&.\e" .Sh RETURN VALUE
 447 \&.\e" 次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。
 448 \&.\e" .Sh ENVIRONMENT
 449 \&.\e" .Sh FILES
 450 \&.\e" .Sh EXAMPLES
 451 \&.\e" 次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。
 452 \&.\e"     ((シェルへの) コマンドの戻り値と
 453 \&.\e"     fprintf/stderr の型の診断です。)
 454 \&.\e" .Sh DIAGNOSTICS
 455 \&.\e" 次の項目はセクション 2, 3, 9 でのみ必要な、
 456 \&.\e" エラーハンドリングとシグナルハンドリングです。
 457 \&.\e" .Sh ERRORS
 458 \&.\e" .Sh SEE ALSO
 459 \&.\e" .Sh CONFORMING TO
 460 \&.\e" .Sh HISTORY
 461 \&.\e" .Sh AUTHORS
 462 \&.\e" .Sh BUGS
 463 .Ed
 464 .Pp
 465 このテンプレートにおける最初の項目はマクロ
 466 .Pq Li \&.Dd , \&.Os , \&.Dt
 467 であり、それぞれドキュメントの日付、
 468 man ページもしくは題材となっているソースの開発や変更のベースとなった
 469 オペレーティングシステム、
 470 .Pq Em 大文字で
 471 man ページタイトルをそのページが属するマニュアルの
 472 セクション番号とともに指定したもの、となっています。
 473 これらのマクロはそのページを識別するものであり、
 474 後述の
 475 .Sx タイトルマクロ
 476 で議論されています。
 477 .Pp
 478 テンプレート中の残りの項目はセクションのヘッダ
 479 .Pq Li \&.Sh
 480 であり、
 481 それらのうち
 482 .Sx NAME
 483 と
 484 .Sx SYNOPSIS
 485 と
 486 .Sx DESCRIPTION
 487 は必須項目です。
 488 これらのヘッダについては
 489 .Sx マニュアル領域
 490 を説明した後、
 491 .Sx ページ構造領域
 492 で議論されます。
 493 いくつかのコンテントマクロはページレイアウトマクロの説明に
 494 使われていますので、ページレイアウトマクロの前にコンテントマクロについて
 495 読むことを推奨します。
 496 .Sh タイトルマクロ
 497 タイトルマクロはページ構造領域の最初の部分ですが、man ページを
 498 前日に書き始めたいという人のために、最初に分けて記述されます。
 499 3 つのヘッダマクロでドキュメントか man ページのタイトル、
 500 オペレーティングシステム、および原著の日付を指定します。
 501 これらのマクロはドキュメントの最初に一度だけ呼び出されるもので、
 502 ヘッダとフッタを構成するためだけに使用されます。
 503 .Bl -tag -width 6n
 504 .It Li \&.Dt ドキュメントタイトル セクション番号 [ボリューム]
 505 .\" .Cl
 506 .\" USD UNIX User's Supplementary Documents
 507 .\" .Cl
 508 .\" PS1 UNIX Programmer's Supplementary Documents
 509 ドキュメントタイトルは man ページの主題であり、troff の制限により
 510 .Tn 大文字
 511 でなければいけません。
 512 セクション番号は 1,\ ...,\ 8 となり、これが指定されると
 513 ボリュームタイトルを省略してもかまいません。
 514 では、次のセクション番号と解説について後述します:
 515 ボリュームタイトルには任意のものか次のいずれかを指定します。
 516 .Pp
 517 .Bl -column SMM -offset indent -compact
 518 .It Li "AMD     UNIX Ancestral Manual Documents"
 519 .It Li "SMM     UNIX System Manager's Manual"
 520 .It Li "URM     UNIX Reference Manual"
 521 .It Li "PRM     UNIX Programmer's Manual"
 522 .El
 523 .Pp
 524 .\" .Cl
 525 .\" MMI UNIX Manual Master Index
 526 .\" .Cl
 527 .\" CON UNIX Contributed Software Manual
 528 .\" .Cl
 529 .\" LOC UNIX Local Manual
 530 デフォルトのボリュームラベルは
 531 セクション 1, 6, 7 では
 532 .Li URM
 533 、
 534 セクション 8 では
 535 .Li SMM
 536 、
 537 セクション 2, 3, 4, 5 では
 538 .Li PRM
 539 となっています。
 540 .It Li \&.Os オペレーティングシステム リリース番号
 541 オペレーティングシステムの名称には一般的な頭字語 (略称)
 542 を使わなければなりません。
 543 例えば、
 544 .Tn BSD
 545 や
 546 .Tn FreeBSD
 547 や
 548 .Tn ATT
 549 といったものです。
 550 リリース番号は、例えば4.3, 4.3+Tahoe, V.3, V.4 というような各システム
 551 での標準のリリースの命名法を使用します。
 552 認識されない引数はページのフッタ中に記述された通りに表示されます。
 553 以下にフッタの典型的な例を示します。
 554 .Pp
 555 .Dl \&.Os 4.3BSD
 556 .Pp
 557 や
 558 .Dl \&.Os FreeBSD 2.2
 559 .Pp
 560 やローカルで生成されたセット
 561 .Pp
 562 .Dl \&.Os CS Department
 563 .Pp
 564 Berkeley でのデフォルトである、引数なしの
 565 .Ql \&.Os
 566 はサイト固有の
 567 ファイル
 568 .Pa /usr/share/tmac/mdoc/doc-common
 569 において
 570 .Tn BSD
 571 として定義されています。
 572 これは実際には
 573 .Tn LOCAL
 574 として定義すべきです。
 575 .Ql \&.Os
 576 マクロがない場合は、ページの左下角は見にくくなるであろうことに
 577 注意してください。
 578 .It Li \&.Dd 月 日, 年
 579 日付は次のようにフォーマルな形式で記述しなければなりません。
 580 .Pp
 581 .ne 5
 582 .Dl January 25, 1989
 583 .El
 584 .Sh マニュアルと一般テキスト領域の紹介
 585 .Ss この名前には何が...?
 586 マニュアル領域のマクロ名はコマンドやサブルーチン、それに関連ファイルを
 587 説明するために使われている日常のインフォーマルな言葉から取られています。
 588 この言葉と少し違うバリエーションのものが man ページを書く上での
 589 3 つの異なった面を記述するのに使われます。
 590 最初のものは
 591 .Nm \-mdoc
 592 マクロ使用方法の説明です。
 593 2 番目のものは
 594 .Nm \-mdoc
 595 マクロを用いた
 596 .Ux
 597 コマンドの記述です。
 598 3 番目はコマンドを通常の言葉の感覚でユーザに示したものです。
 599 これはすなわち、man ページのテキスト中でのコマンドの議論となります。
 600 .Pp
 601 最初のケースでは、
 602 .Xr troff 1
 603 マクロはそれ自身、
 604 一種のコマンドとなっています。
 605 troff コマンドは一般的に以下のような形式をとります。
 606 .Bd -filled -offset indent
 607 \&.Va argument1 argument2 ... argument9
 608 .Ed
 609 .Pp
 610 .Ql \&.Va
 611 はマクロコマンドもしくは要求を示しており、
 612 それに続くものはすべて引数として処理されます。
 613 2 番目のケースでは、コンテントマクロを使用する
 614 .Ux
 615 コマンドの記述がもう少し含まれます。
 616 典型的な
 617 .Sx SYNOPSIS
 618 コマンド行はこのように表示されます。
 619 .Bd -filled -offset indent
 620 .Nm filter
 621 .Op Fl flag
 622 .Ar infile outfile
 623 .Ed
 624 .Pp
 625 ここで
 626 .Nm filter
 627 はコマンド名であり、
 628 角括弧で囲まれた文字列
 629 .Fl flag
 630 は
 631 .Em フラグ
 632 引数で、
 633 これは角括弧で囲むことによってオプションであることを示しています。
 634 .Nm \-mdoc
 635 の用語では
 636 .Ar infile
 637 と
 638 .Ar outfile
 639 は
 640 .Em 引数
 641 と称されています。
 642 上の例のフォーマットを行なったマクロは以下のものです。
 643 .Bd -literal -offset indent
 644 \&.Nm filter
 645 \&.Op \&Fl flag
 646 \&.Ar infile outfile
 647 .Ed
 648 .Pp
 649 3 番目のケースでは、コマンドの説明や構文に上記の例の両方が使われ、
 650 さらに細かい記述が追加されるでしょう。
 651 上の例での引数
 652 .Ar infile
 653 と
 654 .Ar outfile
 655 は
 656 .Em オペランド
 657 もしくは
 658 .Em ファイル引数
 659 として参照されます。
 660 コマンド行の引数のリストはかなり長くなる場合もあります。
 661 .Bl -tag -width make -offset indent
 662 .It Nm make
 663 .Op Fl eiknqrstv
 664 .Op Fl D Ar variable
 665 .Op Fl d Ar flags
 666 .Op Fl f Ar makefile
 667 .Bk -words
 668 .Op Fl I Ar directory
 669 .Ek
 670 .Op Fl j Ar max_jobs
 671 .Op Ar variable=value
 672 .Bk -words
 673 .Op Ar target ...
 674 .Ek
 675 .El
 676 .Pp
 677 ここではコマンド
 678 .Nm make
 679 について記述しており、
 680 .Ar makefile
 681 をフラグ
 682 .Fl f
 683 の引数としています。またオプションの
 684 ファイルオペランド
 685 .Ar target
 686 についても議論しています。
 687 言葉での説明では、こういった詳細な記述が混乱を防いでくれますが、
 688 .Nm \-mdoc
 689 パッケージにはフラグ
 690 .Em への
 691 引数のための
 692 マクロがありません。その代わりに
 693 .Ar target
 694 のような
 695 オペランドやファイル引数に使われる引数マクロ
 696 .Ql \&Ar
 697 が
 698 .Ar variable
 699 のようなフラグへの引数にも使われます。
 700 この make コマンド行は以下の指定により生成されています。
 701 .Bd -literal -offset indent
 702 \&.Nm make
 703 \&.Op Fl eiknqrstv
 704 \&.Op Fl D Ar variable
 705 \&.Op Fl d Ar flags
 706 \&.Op Fl f Ar makefile
 707 \&.Op Fl I Ar directory
 708 \&.Op Fl j Ar max_jobs
 709 \&.Op Ar variable=value
 710 \&.Bk -words
 711 \&.Op Ar target ...
 712 \&.Ek
 713 .Ed
 714 .Pp
 715 マクロ
 716 .Ql \&.Bk
 717 と
 718 .Ql \&.Ek
 719 は
 720 .Sx キープ
 721 セクションにおいて解説されています。
 722 .Ss 一般的な構文
 723 マニュアル領域と一般テキスト領域のマクロはいくつかの小さな違い
 724 があるものの、同様な構文を使用しています。
 725 .Ql \&.Ar ,
 726 .Ql \&.Fl ,
 727 .Ql \&.Nm ,
 728 .Ql \&.Pa
 729 は引数なしで呼び出された時のみ異なります。
 730 .Ql \&.Fn
 731 と
 732 .Ql \&.Xr
 733 は引数のリストの順番が異なります。
 734 マクロ
 735 .Ql \&.Op
 736 と
 737 .Ql \&.Fn
 738 には入れ子の制限があります。
 739 すべてのコンテントマクロが句読点を認識し、正しく扱うには、
 740 各々の句読点文字が先行する空白で分離されている必要があります。
 741 以下のように指定されている場合、
 742 .Pp
 743 .Dl \&.Li sptr, ptr),
 744 .Pp
 745 結果は以下のようになります。
 746 .Pp
 747 .Dl Li sptr, ptr),
 748 .Pp
 749 ここでは句読点は認識されずすべての出力はリテラルなフォントで行なわれて
 750 います。句読点が空白文字で区切られている場合、
 751 .Pp
 752 .Dl \&.Li "sptr , ptr ) ,"
 753 .Pp
 754 結果は以下のようになります。
 755 .Pp
 756 .Dl Li sptr , ptr ) ,
 757 .Pp
 758 今度は句読点が認識され、出力はデフォルトのフォントで行なわれ
 759 リテラルフォントの文字列と区別されています。
 760 .Pp
 761 .Ql \e&
 762 でエスケープすることによって句読点文字の特別な意味を
 763 取り除くことができます。
 764 .Xr troff
 765 はマクロ言語としての限界から、
 766 数学、論理学、もしくは以下の引用符の集合のメンバを含んだ文字列を
 767 表現するのは困難です。
 768 .Bd -literal -offset indent-two
 769 \&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"}
 770 .Ed
 771 .Pp
 772 .Xr troff
 773 が文字によって示唆されている操作もしくは評価を実際に
 774 行なっていることが、その問題の原因となっています。
 775 .Ql \e&
 776 でこれらをエスケープすることによって、
 777 これらの文字が予期せずに評価されることを防止することができます。
 778 最初のコンテントマクロは、以下の
 779 .Ql \&.Ad
 780 において、
 781 その典型的な構文が示されています。
 782 .Sh マニュアル領域
 783 .Ss アドレスマクロ
 784 アドレスマクロは addr1[,addr2[,addr3]] の形式からなる
 785 アドレスを識別します。
 786 .Pp
 787 .Dl 使い方: .Ad address ... \*(Pu
 788 .Bl -tag -width "\&.Ad f1 , f2 , f3 :" -compact -offset 14n
 789 .It Li \&.Ad addr1
 790 .Ad addr1
 791 .It Li \&.Ad addr1\ .
 792 .Ad addr1 .
 793 .It Li \&.Ad addr1\ , file2
 794 .Ad addr1 , file2
 795 .It Li \&.Ad f1\ , f2\ , f3\ :
 796 .Ad f1 , f2 , f3 :
 797 .It Li \&.Ad addr\ )\ )\ ,
 798 .Ad addr ) ),
 799 .El
 800 .Pp
 801 .Ql \&.Ad
 802 を引数なしで呼び出すのはエラーです。
 803 .Ql \&.Ad
 804 は他のマクロから呼び出し可能で解析されます。
 805 .Ss 作者名
 806 .Ql \&.An
 807 マクロは文書化されている項目の作者の名前、もしくは実際の
 808 マニュアルページの作者の名前を指定するために使われます。
 809 名前の情報の後のすべての引数は句読点として扱われます。
 810 .Pp
 811 .Dl 使い方: .An author_name \*(Pu
 812 .Bl -tag -width "\&.An Joe Author ) ) ," -compact -offset 14n
 813 .It Li \&.An Joe\ Author
 814 .An Joe Author
 815 .It Li \&.An Joe\ Author\ ,
 816 .An Joe\ Author ,
 817 .It Li \&.An Joe\ Author\ \&Aq\ nobody@FreeBSD.ORG
 818 .An Joe Author Aq nobody@FreeBSD.ORG
 819 .It Li \&.An Joe\ Author\ )\ )\ ,
 820 .An Joe Author ) ),
 821 .El
 822 .Pp
 823 .Ql \&.An
 824 マクロは解析され、呼び出し可能です。
 825 .Ql \&.An
 826 を引数なしで呼び出すのはエラーです。
 827 .Ss 引数マクロ
 828 引数マクロ
 829 .Ql \&.Ar
 830 はコマンド行の引数を参照する際に
 831 使用することができます。
 832 .Pp
 833 .Dl 使い方: .Ar argument ... \*(Pu
 834 .Bl -tag -width "\&.Ar file1 file2" -compact -offset 15n
 835 .It Li \&.Ar
 836 .Ar
 837 .It Li \&.Ar file1
 838 .Ar file1
 839 .It Li \&.Ar file1\ .
 840 .Ar file1 .
 841 .It Li \&.Ar file1 file2
 842 .Ar file1 file2
 843 .It Li \&.Ar f1 f2 f3\ :
 844 .Ar f1 f2 f3 :
 845 .It Li \&.Ar file\ )\ )\ ,
 846 .Ar file ) ),
 847 .El
 848 .Pp
 849 .Ql \&.Ar
 850 が引数なしで呼び出されると、
 851 .Ql \&.Ar
 852 として扱われます。
 853 .Ql \&.Ar
 854 マクロは解析され、呼び出し可能です。
 855 .Ss コンフィギュレーション宣言 (セクション 4 のみ)
 856 .Ql \&.Cd
 857 マクロはセクション 4 のマニュアルにおいて、
 858 デバイスインタフェースの
 859 .Xr config 8
 860 による宣言の説明に使われます。
 861 このマクロは引用符 (二重引用符のみ) で囲まれた引数を取ることができます。
 862 .Pp
 863 .Bl -tag -width "device le0 at scode?" -offset indent
 864 .It Cd "device le0 at scode?"
 865 は
 866 .Ql ".Cd device le0 at scode?"
 867 によって生成されます。
 868 .El
 869 .Ss コマンド修飾子
 870 コマンド修飾子は
 871 .Ql \&.Cm
 872 マクロがすべての引数の前にダッシュ文字を
 873 付けないことを除いて、
 874 .Ql \&.Fl
 875 (フラグ) コマンドと同じです。
 876 伝統的にフラグはダッシュ文字に引き続いて指定されますが、
 877 いくつかのコマンドやコマンドのサブセットはこの方法を使っていません。
 878 コマンド修飾子はエディタコマンドのような対話的なコマンドでも
 879 指定されることがあります。
 880 .Sx フラグ
 881 のセクションを参照してください。
 882 .Ss 定義済みの変数
 883 インクルードファイルにおいて定義されている変数は
 884 .Ql \&.Dv
 885 マクロによって指定します。
 886 .Pp
 887 .Dl 使い方: .Dv defined_variable ... \*(Pu
 888 .Bl -tag -width "\&.Dv MAXHOSTNAMELEN" -compact -offset 14n
 889 .It Li ".Dv MAXHOSTNAMELEN"
 890 .Dv MAXHOSTNAMELEN
 891 .It Li ".Dv TIOCGPGRP )"
 892 .Dv TIOCGPGRP )
 893 .El
 894 .Pp
 895 .Ql \&.Dv
 896 を引数なしで呼び出すのはエラーです。
 897 .Ql \&.Dv
 898 は解析され、呼び出し可能です。
 899 .Ss errno (セクション 2 のみ)
 900 エラーマクロ
 901 .Ql \&.Er
 902 はセクション 2 のライブラリルーチンにおける
 903 エラーの戻り値を指定します。
 904 下記の 2 番目の例では
 905 .Ql \&.Er
 906 は一般テキスト領域マクロである
 907 .Ql \&.Bq
 908 (これはセクション 2 のマニュアルページで使われています)
 909 と共に使われています。
 910 .Pp
 911 .Dl 使い方: .Er ERRNOTYPE ... \*(Pu
 912 .Bl -tag -width "\&.Bq Er ENOTDIR" -compact -offset 14n
 913 .It Li \&.Er ENOENT
 914 .Er ENOENT
 915 .It Li \&.Er ENOENT\ )\ ;
 916 .Er ENOENT ) ;
 917 .It Li \&.Bq \&Er ENOTDIR
 918 .Bq Er ENOTDIR
 919 .El
 920 .Pp
 921 .Ql \&.Er
 922 を引数なしで呼び出すのはエラーです。
 923 .Ql \&.Er
 924 は解析され、呼び出し可能です。
 925 .Ss 環境変数
 926 .Ql \&.Ev
 927 マクロは環境変数を指定します。
 928 .Pp
 929 .Dl 使い方: .Ev argument ... \*(Pu
 930 .Bl -tag -width "\&.Ev PRINTER ) ) ," -compact -offset 14n
 931 .It Li \&.Ev DISPLAY
 932 .Ev DISPLAY
 933 .It Li \&.Ev PATH\ .
 934 .Ev PATH .
 935 .It Li \&.Ev PRINTER\ )\ )\ ,
 936 .Ev PRINTER ) ),
 937 .El
 938 .Pp
 939 .Ql \&.Ev
 940 を引数なしで呼び出すのはエラーです。
 941 .Ql \&.Ev
 942 は解析され、呼び出し可能です。
 943 .Ss 関数の引数
 944 .Ql \&.Fa
 945 マクロは関数の引数 (パラメータ) を
 946 マニュアルの
 947 .Sx SYNOPSIS
 948 のセクション外、
 949 もしくは
 950 .Sx SYNOPSIS
 951 のセクション内で参照する場合に使われます。
 952 パラメータのリストが
 953 .Ql \&.Fn
 954 マクロでは長すぎる場合は、
 955 囲って使うマクロ
 956 .Ql \&.Fo
 957 と
 958 .Ql \&.Fc
 959 を使わなければなりません。
 960 .Ql \&.Fa
 961 は構造体のメンバを参照する場合にも使われます。
 962 .Pp
 963 .Dl 使い方: .Fa function_argument ... \*(Pu
 964 .Bl -tag -width "\&.Fa d_namlen\ )\ )\ ," -compact -offset 14n
 965 .It Li \&.Fa d_namlen\ )\ )\ ,
 966 .Fa d_namlen ) ),
 967 .It Li \&.Fa iov_len
 968 .Fa iov_len
 969 .El
 970 .Pp
 971 .Ql \&.Fa
 972 を引数なしで呼び出すのはエラーです。
 973 .Ql \&.Fa
 974 は解析され、呼び出し可能です。
 975 .Ss 関数の宣言
 976 .Ql \&.Fd
 977 マクロは
 978 .Sx SYNOPSIS
 979 セクションにおいて、
 980 セクション 2 または 3 の関数の説明で使われます。
 981 .Ql \&.Fd
 982 マクロから他のマクロを呼び出すことはなく、
 983 他のマクロから呼び出すこともできません。
 984 .Pp
 985 .Dl 使い方: .Fd include_file (or defined variable)
 986 .Pp
 987 .Sx SYNOPSIS
 988 セクションにおいて、関数がすでに示されていて改行が
 989 入っていない場合、
 990 .Ql \&.Fd
 991 によって改行が挿入されます。これによって
 992 前の関数呼び出しと次の関数の宣言の間に最適な行間が設定されます。
 993 .Ss フラグ
 994 .Ql \&.Fl
 995 マクロはコマンド行のフラグを扱います。
 996 フラグの前にはダッシュ
 997 .Ql \-
 998 が挿入されます。
 999 対話的なコマンドのフラグでは、ダッシュがフラグの前には挿入されませんが、
1000 .Ql \&.Cm
1001 (コマンド修飾子) マクロは、ダッシュを付けないことを除き、
1002 同じ働きをします。
1003 .Pp
1004 .Dl 使い方: .Fl argument ... \*(Pu
1005 .Bl -tag -width "\&.Fl \-s \-t \-v" -compact -offset 14n
1006 .It Li \&.Fl
1007 .Fl
1008 .It Li \&.Fl cfv
1009 .Fl cfv
1010 .It Li \&.Fl cfv\ .
1011 .Fl cfv .
1012 .It Li \&.Fl s v t
1013 .Fl s v t
1014 .It Li \&.Fl -\ ,
1015 .Fl - ,
1016 .It Li \&.Fl xyz\ )\ ,
1017 .Fl xyz ) ,
1018 .El
1019 .Pp
1020 引数なしで
1021 .Ql \&.Fl
1022 マクロを指定すると、
1023 標準入力/標準出力を意味するダッシュとなります。
1024 ひとつのダッシュに
1025 .Ql \&.Fl
1026 マクロを使用すると、
1027 2 つダッシュとなることに注意して下さい。
1028 .Ql \&.Fl
1029 マクロは解析され、呼び出し可能です。
1030 .Ss 関数 (ライブラリルーチン)
1031 .Ql \&.Fn
1032 マクロは ANSI C の記法を規範としています。
1033 .Bd -literal
1034 使い方: .Fn [type] function [[type] parameters ... \*(Pu]
1035 .Ed
1036 .Bl -tag -width "\&.Fn _int align_ _const * char *sptrsxx" -compact
1037 .It Li "\&.Fn getchar"
1038 .Fn getchar
1039 .It Li "\&.Fn strlen ) ,"
1040 .Fn strlen ) ,
1041 .It Li \&.Fn "\*qint align\*q" "\*qconst * char *sptrs\*q" ,
1042 .Fn "int align" "const * char *sptrs" ,
1043 .El
1044 .Pp
1045 .Ql \&.Fn
1046 を引数を指定せずに呼び出すのはエラーです。
1047 .Ql \&.Fn
1048 マクロは解析され、呼び出し可能です。
1049 他のマクロの呼び出しは
1050 .Ql \&.Fn
1051 の呼び出しの終了を意味することに
1052 注意して下さい (閉じ括弧がその点で挿入されます)。
1053 .Pp
1054 9 個以上のパラメータをとる関数 (これは滅多にないことですが) では、
1055 .Ql \&.Fo
1056 マクロ (関数オープン) と
1057 .Ql \&.Fc
1058 マクロ
1059 (関数クローズ) を
1060 .Ql \&.Fa
1061 (関数引数) と共に使って、
1062 この制限を回避することができます。
1063 以下にその例を示します。
1064 .Bd -literal -offset indent
1065 \&.Fo "int res_mkquery"
1066 \&.Fa "int op"
1067 \&.Fa "char *dname"
1068 \&.Fa "int class"
1069 \&.Fa "int type"
1070 \&.Fa "char *data"
1071 \&.Fa "int datalen"
1072 \&.Fa "struct rrec *newrr"
1073 \&.Fa "char *buf"
1074 \&.Fa "int buflen"
1075 \&.Fc
1076 .Ed
1077 .Pp
1078 これは以下のような結果になります。
1079 .Bd -filled -offset indent
1080 .Fo "int res_mkquery"
1081 .Fa "int op"
1082 .Fa "char *dname"
1083 .Fa "int class"
1084 .Fa "int type"
1085 .Fa "char *data"
1086 .Fa "int datalen"
1087 .Fa "struct rrec *newrr"
1088 .Fa "char *buf"
1089 .Fa "int buflen"
1090 .Fc
1091 .Ed
1092 .Pp
1093 .Ql \&.Fo
1094 と
1095 .Ql \&.Fc
1096 マクロは解析され、呼び出し可能です。
1097 .Sx SYNOPSIS
1098 セクションでは、関数は常に行の先頭から開始されます。
1099 .Sx SYNOPSIS
1100 セクションにおいて、複数の関数が示されており、
1101 関数の型が示されない場合、改行が挿入され、現在の関数名とその前の関数名
1102 の間に最適な改行量が設定されます。現在、
1103 .Ql \&.Fn
1104 は troff の行の長さ
1105 に対して、語の境界をチェックしておらず、予期しない場所で改行が挿入され
1106 てしまうことがあります。これは近い将来修正されるでしょう。
1107 .Ss 関数の型
1108 このマクロは
1109 .Sx SYNOPSIS
1110 セクションで使うものです。
1111 man ページ中の他の場所でも問題なく使うことができますが、
1112 セクション 2 と 3 の
1113 .Sx SYNOPSIS
1114 セクションでカーネルの通常の形式で
1115 関数の型を示すことがこのマクロの目的です (このマクロは関数名が次の行に
1116 置かれるように改行を挿入します)。
1117 .Pp
1118 .Dl 使い方: .Ft type ... \*(Pu
1119 .Bl -tag -width "\&.Ft struct stat" -offset 14n -compact
1120 .It Li \&.Ft struct stat
1121 .Ft struct stat
1122 .El
1123 .Pp
1124 .Ql \&.Ft
1125 は他のマクロからは呼び出せません。
1126 .Ss 対話的なコマンド
1127 .Ql \&.Ic
1128 マクロは対話的なコマンド、もしくは内部コマンドを指定します。
1129 .Pp
1130 .Dl 使い方: .Ic argument ... \*(Pu
1131 .Bl -tag -width "\&.Ic setenv , unsetenvxx" -compact -offset 14n
1132 .It Li \&.Ic :wq
1133 .Ic :wq
1134 .It Li \&.Ic do while {...}
1135 .Ic do while {...}
1136 .It Li \&.Ic setenv\ , unsetenv
1137 .Ic setenv , unsetenv
1138 .El
1139 .Pp
1140 .Ql \&.Ic
1141 を引数なしで呼び出すのはエラーです。
1142 .Ql \&.Ic
1143 マクロは解析され、呼び出し可能です。
1144 .Ss 名前マクロ
1145 .Ql \&.Nm
1146 マクロは文書のタイトルやサブジェクト名を指定するために
1147 使われます。このマクロは最初に呼び出された時の引数を覚えておくという
1148 特性を持っており、それは常にそのページのサブジェクト名であるべきです。
1149 引数なしで呼び出されると
1150 .Ql \&.Nm
1151 は作者の作業を少なくするためだけの
1152 目的で、最初の名称を出力します。注意: セクション 2 または 3 のドキュメント
1153 の関数名は
1154 .Sx NAME
1155 セクションにおいて
1156 .Ql \&.Nm
1157 で指定され、
1158 .Sx SYNOPSIS
1159 セクションや残りのセクションでは
1160 .Ql \&.Fn
1161 で指定され
1162 ます。
1163 .Xr csh 1
1164 での
1165 .Ql while
1166 コマンドのキーワードのような対話的
1167 なコマンドでは
1168 .Ql \&.Ic
1169 マクロを使うべきです。
1170 .Ql \&.Ic
1171 は
1172 ほとんど
1173 .Ql \&.Nm
1174 と同一ですが、それが最初に使われたときの引数を
1175 記憶することはできません。
1176 .Pp
1177 .Dl 使い方: .Nm argument ... \*(Pu
1178 .Bl -tag -width "\&.Nm mdoc.sample" -compact -offset 14n
1179 .It Li \&.Nm mdoc.sample
1180 .Nm mdoc.sample
1181 .It Li \&.Nm \e-mdoc
1182 .Nm \-mdoc .
1183 .It Li \&.Nm foo\ )\ )\ ,
1184 .Nm foo ) ),
1185 .It Li \&.Nm
1186 .Nm
1187 .El
1188 .Pp
1189 .Ql \&.Nm
1190 マクロは解析され、呼び出し可能です。
1191 .Ss オプション
1192 .Ql \&.Op
1193 マクロはコマンド行の残りのすべての引数をオプションである
1194 ことを示す角括弧で囲み、末尾の句読点は角括弧の外に置きます。
1195 .Ql \&.Oc
1196 マクロと
1197 .Ql \&.Oo
1198 マクロは複数行に渡って使うことが
1199 できます。
1200 .Pp
1201 .Dl 使い方: .Op options ... \*(Pu
1202 .Bl -tag -width "\&.Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent
1203 .It Li \&.Op
1204 .Op
1205 .It Li ".Op Fl k"
1206 .Op Fl k
1207 .It Li ".Op Fl k ) ."
1208 .Op Fl k ) .
1209 .It Li ".Op Fl k Ar kookfile"
1210 .Op Fl k Ar kookfile
1211 .It Li ".Op Fl k Ar kookfile ,"
1212 .Op Fl k Ar kookfile ,
1213 .It Li ".Op Ar objfil Op Ar corfil"
1214 .Op Ar objfil Op Ar corfil
1215 .It Li ".Op Fl c Ar objfil Op Ar corfil ,"
1216 .Op Fl c Ar objfil Op Ar corfil ,
1217 .It Li \&.Op word1 word2
1218 .Op word1 word2
1219 .El
1220 .Pp
1221 .Ql \&.Oc
1222 マクロと
1223 .Ql \&.Oo
1224 マクロ:
1225 .Bd -literal -offset indent
1226 \&.Oo
1227 \&.Op \&Fl k \&Ar kilobytes
1228 \&.Op \&Fl i \&Ar interval
1229 \&.Op \&Fl c \&Ar count
1230 \&.Oc
1231 .Ed
1232 .Pp
1233 生成結果:
1234 .Oo
1235 .Op Fl k Ar kilobytes
1236 .Op Fl i Ar interval
1237 .Op Fl c Ar count
1238 .Oc
1239 .Pp
1240 .Ql \&.Op
1241 と
1242 .Ql \&.Oc
1243 と
1244 .Ql \&.Oo
1245 マクロは
1246 解析され、呼び出し可能です。
1247 .Ss パス名
1248 .Ql \&.Pa
1249 マクロはパス名もしくはファイル名をフォーマットします。
1250 .Pp
1251 .Dl 使い方: .Pa pathname \*(Pu
1252 .Bl -tag -width "\&.Pa /tmp/fooXXXXX ) ." -compact -offset 14n
1253 .It Li \&.Pa /usr/share
1254 .Pa /usr/share
1255 .It Li \&.Pa /tmp/fooXXXXX\ )\ .
1256 .Pa /tmp/fooXXXXX ) .
1257 .El
1258 .Pp
1259 .Ql \&.Pa
1260 マクロは解析され、呼び出し可能です。
1261 .Ss 変数
1262 一般的な変数への参照です。
1263 .Pp
1264 .Dl 使い方: .Va variable ... \*(Pu
1265 .Bl -tag -width "\&.Va char s ] ) ) ," -compact -offset 14n
1266 .It Li \&.Va count
1267 .Va count
1268 .It Li \&.Va settimer ,
1269 .Va settimer ,
1270 .It Li \&.Va int\ *prt\ )\ :
1271 .Va int\ *prt ) :
1272 .It Li \&.Va char\ s\ ]\ )\ )\ ,
1273 .Va char\ s ] )),
1274 .El
1275 .Pp
1276 .Ql \&.Va
1277 を引数なしで呼び出すのはエラーです。
1278 .Ql \&.Va
1279 マクロは解析され、呼び出し可能です。
1280 .Ss マニュアルページの相互参照
1281 .Ql \&.Xr
1282 マクロは最初の引数にマニュアルページの名称を取り、
1283 もしあれば次の引数にセクションのページ数か句読点を取ります。
1284 すべての残りの引数は句読点と見なされます。
1285 .Pp
1286 .Dl 使い方: .Xr man_page [1,...,8] \*(Pu
1287 .Bl -tag -width "\&.Xr mdoc 7 ) ) ," -compact -offset 14n
1288 .It Li \&.Xr mdoc
1289 .Xr mdoc
1290 .It Li \&.Xr mdoc\ ,
1291 .Xr mdoc ,
1292 .It Li \&.Xr mdoc 7
1293 .Xr mdoc 7
1294 .It Li \&.Xr mdoc 7\ )\ )\ ,
1295 .Xr mdoc 7 ) ),
1296 .El
1297 .Pp
1298 .Ql \&.Xr
1299 マクロは解析され、呼び出し可能です。
1300 .Ql \&.Xr
1301 を引数なしで呼び出すのはエラーです。
1302 .Sh 一般テキスト領域
1303 .Ss AT&T マクロ
1304 .Bd -literal -offset indent -compact
1305 使い方: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu
1306 .Ed
1307 .Bl -tag -width "\&.At v6 ) ," -compact -offset 14n
1308 .It Li .At
1309 .At
1310 .It Li ".At v6 ."
1311 .At v6 .
1312 .El
1313 .Pp
1314 .Ql \&.At
1315 マクロは解析
1316 .Em されず
1317 、呼び出し
1318 .Em 不可
1319 です。
1320 最大 2 つまでの引数を取ることができます。
1321 .Ss BSD マクロ
1322 .Dl 使い方: .Bx [Version/release] ... \*(Pu
1323 .Bl -tag -width "\&.Bx 4.3 ) ," -compact -offset 14n
1324 .It Li .Bx
1325 .Bx
1326 .It Li ".Bx 4.3 ."
1327 .Bx 4.3 .
1328 .El
1329 .Pp
1330 .Ql \&.Bx
1331 マクロは解析され、呼び出し可能です。
1332 .Ss FreeBSD マクロ
1333 .Bd -literal -offset indent -compact
1334 使い方: .Fx Version.release ... \*(Pu
1335 .Ed
1336 .Bl -tag -width "\&.Fx 2.2 ) ," -compact -offset 14n
1337 .It Li ".Fx 2.2 ."
1338 .Fx 2.2 .
1339 .El
1340 .Pp
1341 .Ql \&.Fx
1342 マクロは解析
1343 .Em されず
1344 、呼び出し
1345 .Em 不可
1346 です。
1347 最大 2 つまでの引数を取ることができます。
1348 .Ss UNIX マクロ
1349 .Dl 使い方: .Ux ... \*(Pu
1350 .Bl -tag -width "\&.Ux 4.3 ) ," -compact -offset 14n
1351 .It Li .Ux
1352 .Ux
1353 .El
1354 .Pp
1355 .Ql \&.Ux
1356 マクロは解析され、呼び出し可能です。
1357 .Ss 囲い/クォートマクロ
1358 囲いの概念はクォートと似たものです。
1359 1 つ以上の文字列が引用符や括弧のような文字のペアで囲まれている
1360 オブジェクトを指します。
1361 クォートと囲いという用語はこの文書を通して同じ意味で使われます。
1362 ほとんどの 1 行の囲いマクロはクォート (quote) のヒントとするために、
1363 小文字の
1364 .Ql q
1365 で終了しますが、いくつかの例外があります。
1366 各々の囲いマクロに対し、開始マクロと終了マクロのペアもあり、
1367 それぞれ小文字の
1368 .Ql o
1369 と
1370 .Ql c
1371 で終了します。
1372 これらは 1 行以上のテキストに渡って使うことができますが、
1373 入れ子にする場合に制限があります。
1374 その中では 1 行形式のクォートマクロのみ使用することができます。
1375 .Pp
1376 .ne 5
1377 .Bd -filled -offset indent
1378 .Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX
1379 .Em "クォート       終了  開始  機能  結果"
1380 \&.Aq   .Ac     .Ao     カギ括弧による囲い     <文字列>
1381 \&.Bq   .Bc     .Bo     角括弧による囲い        [文字列]
1382 \&.Dq   .Dc     .Do     二重引用符 ``文字列''
1383         .Ec     .Eo     囲い文字列 (XXによる)   XX文字列XX
1384 \&.Pq   .Pc     .Po     括弧による囲い   (文字列)
1385 \&.Ql                   クォートされたリテラル       `st' or 文字列
1386 \&.Qq   .Qc     .Qo     まっすぐな二重引用符  "文字列"
1387 \&.Sq   .Sc     .So     一重引用符 `文字列'
1388 .El
1389 .Ed
1390 .Pp
1391 下記の不正なマクロを除き、すべてのクォートマクロは解析され、呼び出し
1392 可能です。句読点がひとつずつ置かれていて、スペースで区切られていれば、
1393 すべてのクォートマクロは句読点を適切に扱います。クォートマクロは開く
1394 句読点、閉じる句読点(訳注: 句読点には括弧なども含みます) を調べ、
1395 それが囲む文字列より前か後かを決めます。これによって、ある程度の入れ子
1396 が可能になっています。
1397 .Bl -tag -width xxx,xxxx
1398 .It Li \&.Ec , \&.Eo
1399 これらのマクロは各々開始および終了の文字列を最初の引数に取ります。
1400 .It Li \&.Ql
1401 リテラルをクォートするマクロは
1402 .Xr troff
1403 では
1404 .Xr nroff
1405 と異なっ
1406 た処理を行ないます。
1407 .Xr nroff
1408 でフォーマットされた場合、クォート指定
1409 されたリテラルは常にクォートされます。
1410 .Xr troff
1411 でフォーマットされた
1412 場合は、アイテムの幅が固定幅文字 3 つ分より狭い場合にのみクォートされま
1413 す。これはリテラル (固定幅) のフォントの変更があまり気づかれないもので
1414 あるため、短い文字列を良く見えるようにするためです。
1415 .It Li \&.Pf
1416 プレフィックスマクロは呼び出し可能ではありませんが、解析されます。
1417 .Bl -tag -width (namexx -offset indent
1418 .It Li ".Pf ( Fa name2"
1419 は
1420 .Pf ( Fa name2
1421 となります。
1422 .El
1423 .Pp
1424 .Ql \&.Ns
1425 (空白なし) マクロはサフィックス機能と同様の作用があります。
1426 .El
1427 .Pp
1428 .ne 4
1429 クォートの例:
1430 .Bl -tag -width "\&.Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent
1431 .It Li \&.Aq
1432 .Aq
1433 .It Li \&.Aq \&Ar ctype.h\ )\ ,
1434 .Aq Ar ctype.h ) ,
1435 .It Li \&.Bq
1436 .Bq
1437 .It Li \&.Bq \&Em Greek \&, French \&.
1438 .Bq Em Greek , French .
1439 .It Li \&.Dq
1440 .Dq
1441 .It Li ".Dq string abc ."
1442 .Dq string abc .
1443 .It Li ".Dq \'^[A-Z]\'"
1444 .Dq \'^[A-Z]\'
1445 .It Li "\&.Ql man mdoc"
1446 .Ql man mdoc
1447 .It Li \&.Qq
1448 .Qq
1449 .It Li "\&.Qq string ) ,"
1450 .Qq string ) ,
1451 .It Li "\&.Qq string Ns ),"
1452 .Qq string Ns ),
1453 .It Li \&.Sq
1454 .Sq
1455 .It Li "\&.Sq string"
1456 .Sq string
1457 .El
1458 .Pp
1459 囲いマクロの入れ子についての良い例については、
1460 オプションマクロ
1461 .Ql \&.Op
1462 を参照してください。
1463 このマクロは上でリストされているような囲いマクロと同じベースの上に
1464 作られています。
1465 拡張引数リストマクロ
1466 .Ql \&.Xo
1467 と
1468 .Ql \&.Xc
1469 もまた同じルーチンを
1470 ベースに作られており、
1471 .Nm \-mdoc
1472 マクロの使い方の非常に良い例と
1473 なっています。
1474 .Ss no\-op もしくは通常テキストマクロ
1475 .Ql \&.No
1476 マクロはマクロコマンド行において、コンテントマクロの構文
1477 形式に従うが、フォーマットされては
1478 .Em ならない
1479 単語をハックする
1480 ものです。
1481 .Ss 空白なしマクロ
1482 .Ql \&.Ns
1483 マクロはマクロ間での不要な空白を除去します。
1484 これはフラグと引数の間に空白を含まない古いスタイルの引数リストを使う
1485 場合に便利です。
1486 .Bl -tag -width "\&.Op Fl I Ns Ar directoryxx" -offset indent
1487 .It Li ".Op Fl I Ns Ar directory"
1488 は
1489 .Op Fl I Ns Ar directory
1490 という結果になります。
1491 .El
1492 .Pp
1493 注:
1494 .Ql \&.Ns
1495 マクロは他のマクロ名が続かなければ、
1496 スペースを除去したあとに
1497 .Ql \&.No
1498 マクロを常に起動します。
1499 .Ql \&.Ns
1500 マクロは解析され、呼び出し可能です。
1501 .Ss セクションの相互参照
1502 .Ql \&.Sx
1503 マクロは同一文書内でのセクションのヘッダへの参照を
1504 指定します。これは解析され、呼び出し可能です。
1505 .Pp
1506 .Bl -tag -width "Li \&.Sx FILES" -offset 14n
1507 .It Li \&.Sx FILES
1508 .Sx FILES
1509 .El
1510 .Ss 相互参照と引用
1511 以下のマクロは多少なりとも参考文献を扱えるようにと意図したものです。
1512 これらのマクロは、せいぜい参照スタイルの参考文献のサブセットを手動で
1513 作成しやすくする程度です。
1514 .Pp
1515 .Bl -tag -width 6n -offset indent -compact
1516 .It Li .Rs
1517 参考文献の開始。
1518 改行を挿入してから、参考文献の終了マクロが読み込まれるまで
1519 参考文献の情報を収集する。
1520 .It Li .Re
1521 参考文献の終了。参考文献が表示される。
1522 .It Li .%A
1523 参考文献の作者名。1 回の呼び出しにつき、作者名をひとつ指定する。
1524 .It Li .%B
1525 書籍のタイトル。
1526 .It Li .\&%C
1527 都市/場所。
1528 .It Li .\&%D
1529 日付。
1530 .It Li .%J
1531 定期刊行物の名称。
1532 .It Li .%N
1533 発行番号。
1534 .It Li .%O
1535 追加の情報。
1536 .It Li .%P
1537 ページ番号。
1538 .It Li .%R
1539 報告書の名称。
1540 .It Li .%T
1541 記事のタイトル。
1542 .It Li .%V
1543 巻数。
1544 .El
1545 .Pp
1546 .Ql %
1547 で始まるマクロは呼び出し不可能ですが、
1548 呼び出し側に戻る商標名マクロだけは解析されます。
1549 (現時点では予期できないことです。)
1550 商標名のみ解析されるのは
1551 .Xr troff Ns / Ns Xr ditroff
1552 の出力を
1553 きれいにするためです。
1554 .Ss 返り値
1555 .Ql \&.Rv
1556 マクロは
1557 .Sx RETURN VALUE
1558 のセクション
1559 で使うテキストを生成します。
1560 .Pp
1561 .Dl 使い方: .Rv [-std function]
1562 .Pp
1563 .Ql \&.Rv -std atexit
1564 は以下のテキストを生成します。
1565 .Pp
1566 .\" fake section 3 to avoid error message from Rv
1567 .\".ds cH 3
1568 .ds section 3
1569 .\" and back to 7 again
1570 .\".ds cH 7
1571 .Rv -std atexit
1572 .ds section 7
1573 .Pp
1574 .Fl std
1575 オプションはセクション 2 と 3 のマニュアルページでのみ有効です。
1576 .Ss 商標名 (頭文字とタイプ名)
1577 商標名マクロは一般的に長さが 2 文字を越えるすべてが大文字の単語用に
1578 使われる小さな大文字のマクロです。
1579 .Pp
1580 .Dl 使い方: .Tn symbol ... \*(Pu
1581 .Bl -tag -width "\&.Tn ASCII" -compact -offset 14n
1582 .It Li \&.Tn DEC
1583 .Tn DEC
1584 .It Li \&.Tn ASCII
1585 .Tn ASCII
1586 .El
1587 .Pp
1588 .Ql \&.Tn
1589 マクロは解析され、他のマクロから呼び出し可能です。
1590 .Ss 拡張引数
1591 .Ql \&.Xo
1592 と
1593 .Ql \&.Xc
1594 マクロでマクロの境界における引数リストを
1595 拡張することができます。引数リストは
1596 .Ql \&.Op
1597 のようなすべての引数
1598 が 1 行中に指定されていることを前提としているマクロの中では行に渡って
1599 拡張することができません。
1600 .Pp
1601 以下に空白モードマクロをスペーシングをオフにするために
1602 使った
1603 .Ql \&.Xo
1604 での例を示します。
1605 .Bd -literal -offset indent
1606 \&.Sm off
1607 \&.It Xo Sy I Ar operation
1608 \&.No \een Ar count No \een
1609 \&.Xc
1610 \&.Sm on
1611 .Ed
1612 .Pp
1613 これは以下のような結果になります。
1614 .Bd -filled -offset indent
1615 .Bl -tag -width flag -compact
1616 .Sm off
1617 .It Xo Sy I Ar operation
1618 .No \en Ar count No \en
1619 .Xc
1620 .Sm on
1621 .El
1622 .Ed
1623 .Pp
1624 例をもうひとつ:
1625 .Bd -literal -offset indent
1626 \&.Sm off
1627 \&.It Cm S No \&/ Ar old_pattern Xo
1628 \&.No \&/ Ar new_pattern
1629 \&.No \&/ Op Cm g
1630 \&.Xc
1631 \&.Sm on
1632 .Ed
1633 .Pp
1634 これは以下のような結果になります。
1635 .Bd -filled -offset indent
1636 .Bl -tag -width flag -compact
1637 .Sm off
1638 .It Cm S No \&/ Ar old_pattern Xo
1639 .No \&/ Ar new_pattern
1640 .No \&/ Op Cm g
1641 .Xc
1642 .Sm on
1643 .El
1644 .Ed
1645 .Pp
1646 囲いマクロを使った
1647 .Ql \&.Xo
1648 の他の例:
1649 変数の値をテストして下さい。
1650 .Bd -literal -offset indent
1651 \&.It Xo
1652 \&.Ic .ifndef
1653 \&.Oo \e&! Oc Ns Ar variable
1654 \&.Op Ar operator variable ...
1655 \&.Xc
1656 .Ed
1657 .Pp
1658 これは以下のような結果になります。
1659 .Bd -filled -offset indent
1660 .Bl -tag -width flag -compact
1661 .It Xo
1662 .Ic .ifndef
1663 .Oo \&! Oc Ns Ar variable
1664 .Op Ar operator variable ...
1665 .Xc
1666 .El
1667 .Ed
1668 .Pp
1669 上のすべての例では
1670 .Ql \&.It
1671 (リスト項目) マクロの
1672 引数リストに
1673 .Ql \&.Xo
1674 マクロを使用しています。
1675 拡張マクロが使われることはあまりありません。使われるとすれば、リスト
1676 項目の引数リストを拡張する場合です。残念なことに、これが拡張マクロが
1677 最も懲り性であるところでもあります。最初の 2 つの例では、スペーシングは
1678 オフになっています。3 番目では、ある箇所にはスペーシングを入れることが
1679 望ましいのですが、出力全体に入れたいわけではありません。そのような状況
1680 でこれらのマクロが適切に動作するためには、
1681 .Ql \&.Xo
1682 と
1683 .Ql \&.Xc
1684 マクロが 3 番目の例にあるように指定されていることを確認してください。
1685 .Ql \&.Xo
1686 マクロが置かれた
1687 .Ql \&.It
1688 の引数リストに他のものが
1689 置かれると、スペーシングがどうなるかは予測不可能です。
1690 この場合、
1691 .Ql \&.Ns
1692 (空白なしマクロ) は行中の最初もしくは最後の
1693 マクロに指定してはいけません。現在
1694 .Bx
1695 でリリースされている 900 の
1696 マニュアルページ (実際のページでは約 1500 ページ) のうち 15 の
1697 マニュアルページでのみしか
1698 .Ql \&.Xo
1699 が使われていません。
1700 .Sh ページ構造のドメイン
1701 .Ss セクションヘッダ
1702 以下にリストされている、最初の 3 つのセクションヘッダマクロ
1703 .Ql \&.Sh
1704 はすべての man ページで必須のものです。
1705 残りのセクションヘッダはマニュアルページの作者の裁量において、
1706 推奨されているものです。
1707 .Ql \&.Sh
1708 マクロは 9 つまでの引数を取ることができます。
1709 これは解析されますが、呼び出し不可能です。
1710 .Bl -tag -width "\&.Sh SYNOPSIS"
1711 .It \&.Sh 名前
1712 .Sh 名前
1713 (NAME) マクロは必須のものです。
1714 これが指定されていないと、ヘッダとフッタ、それにデフォルトの
1715 ページレイアウトが設定されず、結果はかなり好ましくないものになるでしょう。
1716 .Sx NAME
1717 セクションは最低 3 つの項目からなります。
1718 最初のものは名称マクロ
1719 .Ql \&.Nm
1720 であり、man ページのサブジェクトと
1721 なります。2 番目のものは名称説明マクロ
1722 .Ql \&.Nd
1723 であり、
1724 サブジェクト名を 3 つめの項目、すなわちその名称の説明と分離します。
1725 説明に割り当てられるスペースは小さいものですので、
1726 できるだけ簡潔で分かりやすいものでなければなりません。
1727 .It \&.Sh 書式
1728 .Sx 書式
1729 (SYNOPSIS) セクションはその man ページのサブジェクト
1730 となっている項目の典型的な使用法を説明します。
1731 必須のマクロは
1732 .Ql ".Nm" ,
1733 .Ql ".Cd" ,
1734 .Ql ".Fn"
1735 のいずれかです。
1736 (他には
1737 .Ql ".Fo" ,
1738 .Ql ".Fc" ,
1739 .Ql ".Fd" ,
1740 .Ql ".Ft"
1741 の
1742 マクロも必要な場合があります。)
1743 関数名マクロ
1744 .Ql ".Fn"
1745 はセクション 2 と 3 のマニュアルページに
1746 おいて必須のもので、コマンドと一般名称マクロ
1747 .Ql \&.Nm
1748 は
1749 セクション 1, 5, 6, 7, 8 で必須の項目です。
1750 セクション 4 のマニュアルでは
1751 .Ql ".Nm"
1752 か
1753 .Ql ".Fd"
1754 、もしくは
1755 コンフィギュレーションデバイス使用法マクロ
1756 .Ql ".Cd"
1757 が必要です。
1758 その他のいくつかのマクロが下に示すような書式行を生成するために必要な
1759 ことがあります。
1760 .El
1761 .Pp
1762 .Bd -filled -offset indent
1763 .Nm cat
1764 .Op Fl benstuv
1765 .Op Fl
1766 .Ar
1767 .Ed
1768 .Pp
1769 以下のマクロが使われています。
1770 .Pp
1771 .Dl \&.Nm cat
1772 .Dl \&.Op \&Fl benstuv
1773 .Dl \&.Op \&Fl
1774 .Dl \&.Ar
1775 .Pp
1776 .Sy 注 :
1777 マクロ
1778 .Ql \&.Op ,
1779 .Ql \&.Fl ,
1780 .Ql \&.Ar
1781 は
1782 パイプの文字
1783 .Ql \*(Ba
1784 を認識し、下記のようなコマンド行
1785 .Pp
1786 .Dl ".Op Fl a | Fl b"
1787 .Pp
1788 はうまくいきません。
1789 .Xr troff
1790 は通常 \*(Ba を特別のオペレータとして
1791 解釈します。この他で \*(Ba が使える場合については
1792 .Sx 定義済みの文字列
1793 セクションを参照して下さい。
1794 .Bl -tag
1795 .It \&.Sh 説明
1796 .Sx 説明
1797 (DESCRIPTION) セクションでの最初のテキストは、
1798 ほとんどの場合ではそのコマンド、関数もしくはファイルについての短い
1799 段落で、オプションの構文リストとそれぞれの説明がそれに続きます。
1800 そのようなリストを作成するには
1801 リスト開始マクロ
1802 .Ql \&.Bl
1803 、リスト項目マクロ
1804 .Ql \&.It
1805 、
1806 リスト終了マクロ
1807 .Ql \&.El
1808 を使います
1809 (後述の
1810 .Sx リストと列
1811 セクションを参照)。
1812 .El
1813 .Pp
1814 以下の
1815 .Ql \&.Sh
1816 のセクションヘッダはマニュアルページの好ましい
1817 レイアウトの一部であり、一貫性を保つために適切に使われなければ
1818 なりません。これらは使われる順番にリストされています。
1819 .Bl -tag -width SYNOPSIS
1820 .It \&.Sh 環境変数
1821 .Sx 環境変数
1822 (ENVIRONMENT) セクションは関連する環境変数を明らかにし、
1823 それらの振舞いや使用方法を示します。
1824 .It \&.Sh 例
1825 使用例、実行例を作成するには様々な方法があります。
1826 詳細については、下の
1827 .Sx 例
1828 のセクションを参照してください。
1829 .It \&.Sh ファイル
1830 man ページのサブジェクトによって使用されるか生成されるファイルで、
1831 .Sx ファイル
1832 のセクション中でマクロ
1833 .Ql \&.Pa
1834 によってリスト
1835 されます。
1836 .It \&.Sh 関連項目
1837 .Sx 関連項目
1838 (SEE ALSO) セクションには、その man ページの題材に
1839 関する資料への参照と他の関連する man ページへのクロスリファレンスが
1840 記載されます。クロスリファレンスは
1841 .Ql \&.Xr
1842 マクロによって指定
1843 されます。
1844 .Sx 関連項目
1845 セクションでのクロスリファレンスは
1846 セクション番号順に並べ、セクション中ではカンマで区切って
1847 アルファベット順に並べなければなりません。以下に例を示します。
1848 .Pp
1849 .Xr ls 1 ,
1850 .Xr ps 1 ,
1851 .Xr group 5 ,
1852 .Xr passwd 5 .
1853 .Pp
1854 ここで参考スタイルである
1855 .Xr refer 1
1856 は適応されていません。
1857 .It \&.Sh 準拠
1858 コマンドやライブラリ関数やファイルが、
1859 .St -p1003.2
1860 や
1861 .St -ansiC
1862 のような特定の実装によるものであれば、ここで記述します。
1863 コマンドがどの規格にも基づいていなければ、その歴史は
1864 .Sx 歴史
1865 (HISTORY)のセクションで説明されなければなりません。
1866 .It \&.Sh 歴史
1867 特定の規格に基づいていないコマンドは、
1868 このセクションでその歴史の概要が説明されるべきです。
1869 .It \&.Sh 作者
1870 クレジットが必要であれば、ここで入れます。
1871 .It \&.Sh 診断
1872 コマンドからの診断はこのセクションに入れます。
1873 .It \&.Sh エラー
1874 特定のエラーハンドリング、特にライブラリ関数
1875 (man ページのセクション 2, 3, 9) でのエラーハンドリングは、ここで説明します。
1876 .Ql \&.Er
1877 マクロが errno を記述するために使われます。
1878 .It \&.Sh バグ
1879 あきらかな問題はここで記述します...
1880 .El
1881 .Pp
1882 ユーザ指定の
1883 .Ql \&.Sh
1884 セクションを追加することができます。
1885 たとえば、このセクションは以下のように設定されています。
1886 .Bd -literal -offset 14n
1887 \&.Sh ページ構造領域
1888 .Ed
1889 .Ss 段落と行スペース
1890 .Bl -tag -width 6n
1891 .It \&.Pp
1892 .Ql \&.Pp
1893 段落コマンドは必要な場合に行スペースを指定するために使われます。
1894 このマクロは、
1895 .Ql \&.Sh
1896 マクロや
1897 .Ql \&.Ss
1898 マクロの後や、
1899 .Ql \&.Bl
1900 マクロの前では必要ありません。
1901 (
1902 .Ql \&.Bl
1903 マクロは -compact フラグが指定されていなければ、
1904 縦方向の距離を宣言します)。
1905 .El
1906 .\" This worked with version one, need to redo for version three
1907 .\" .Pp
1908 .\" .Ds I
1909 .\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
1910 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
1911 .\" .Cl Cx \t\t
1912 .\" .Li \&.Cx\ (
1913 .\" .Cx
1914 .\" .Cl Cx \t\t
1915 .\" .Li \&.Va ax
1916 .\" .Cx
1917 .\" .Cl Cx \t\t
1918 .\" .Li \&.Sy \+
1919 .\" .Cx
1920 .\" .Cl Cx \&(\&
1921 .\" .Va ax
1922 .\" .Cx +
1923 .\" .Va by
1924 .\" .Cx +
1925 .\" .Va c )
1926 .\" .Cx \t
1927 .\" .Em is produced by
1928 .\" .Cx \t
1929 .\" .Li \&.Va by
1930 .\" .Cx
1931 .\" .Cl Cx \t\t
1932 .\" .Li \&.Sy \+
1933 .\" .Cx
1934 .\" .Cl Cx \t\t
1935 .\" .Li \&.Va c )
1936 .\" .Cx
1937 .\" .Cl Cx \t\t
1938 .\" .Li \&.Cx
1939 .\" .Cx
1940 .\" .Cw
1941 .\" .De
1942 .\" .Pp
1943 .\" This example shows the same equation in a different format.
1944 .\" The spaces
1945 .\" around the
1946 .\" .Li \&+
1947 .\" signs were forced with
1948 .\" .Li \e :
1949 .\" .Pp
1950 .\" .Ds I
1951 .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
1952 .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
1953 .\" .Cl Cx \t\t
1954 .\" .Li \&.Cx\ (
1955 .\" .Cx
1956 .\" .Cl Cx \t\t
1957 .\" .Li \&.Va a
1958 .\" .Cx
1959 .\" .Cl Cx \t\t
1960 .\" .Li \&.Sy x
1961 .\" .Cx
1962 .\" .Cl Cx \t\t
1963 .\" .Li \&.Cx \e\ +\e\ \e&
1964 .\" .Cx
1965 .\" .Cl Cx \&(\&
1966 .\" .Va a
1967 .\" .Sy x
1968 .\" .Cx \ +\ \&
1969 .\" .Va b
1970 .\" .Sy y
1971 .\" .Cx \ +\ \&
1972 .\" .Va c )
1973 .\" .Cx \t
1974 .\" .Em is produced by
1975 .\" .Cl Cx \t\t
1976 .\" .Li \&.Va b
1977 .\" .Cx
1978 .\" .Cl Cx \t\t
1979 .\" .Li \&.Sy y
1980 .\" .Cx
1981 .\" .Cl Cx \t\t
1982 .\" .Li \&.Cx \e\ +\e\ \e&
1983 .\" .Cx
1984 .\" .Cl Cx \t\t
1985 .\" .Li \&.Va c )
1986 .\" .Cx
1987 .\" .Cl Cx \t\t
1988 .\" .Li \&.Cx
1989 .\" .Cx
1990 .\" .Cw
1991 .\" .De
1992 .\" .Pp
1993 .\" The incantation below was
1994 .\" lifted from the
1995 .\" .Xr adb 1
1996 .\" manual page:
1997 .\" .Pp
1998 .\" .Ds I
1999 .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
2000 .\" .Cl Cx \t\t
2001 .\" .Li \&.Cx Op Sy ?/
2002 .\" .Cx
2003 .\" .Cl Cx \t\t
2004 .\" .Li \&.Nm m
2005 .\" .Cx
2006 .\" .Cl Cx Op Sy ?/
2007 .\" .Nm m
2008 .\" .Ad \ b1 e1 f1
2009 .\" .Op Sy ?/
2010 .\" .Cx \t
2011 .\" .Em is produced by
2012 .\" .Cx \t
2013 .\" .Li \&.Ar \e\ b1 e1 f1
2014 .\" .Cx
2015 .\" .Cl Cx \t\t
2016 .\" .Li \&.Op Sy ?/
2017 .\" .Cx
2018 .\" .Cl Cx \t\t
2019 .\" .Li \&.Cx
2020 .\" .Cx
2021 .\" .Cw
2022 .\" .De
2023 .\" .Pp
2024 .Ss キープ
2025 現在実装されているキープは単語に対するものだけです。
2026 それらは
2027 .Ql \&.Bk
2028 (キープ開始) マクロと
2029 .Ql \&.Ek
2030 (キープ終了)
2031 マクロです。
2032 .Ql \&.Bk
2033 に指定できるオプションは
2034 .Fl words
2035 のみで
2036 あり、これはオプションの途中で改行が入らないようにするのに便利です。
2037 コマンド行の引数を生成する例 (
2038 .Sx この名前には何が...?
2039 セクションを
2040 参照) において、キープは
2041 .Xr nroff
2042 がフラグと引数を別の行に分けない
2043 ように使われています。 (実際には、オプションマクロがこの目的で使われて
2044 いましたが、オプションが行中にわたって散らばってしまうと一般的に見栄え
2045 が悪くなるという理由により
2046 .Xr troff
2047 で右揃えのマージンを強制的に
2048 行なう (宗教的な) 決定がなされてから、オプションマクロをこの目的で
2049 使わないようになりました。キープマクロについてはもっと機能を向上する
2050 作業が必要であり、
2051 .Fl line
2052 オプションを追加していく必要があります。)
2053 .Ss 例やディスプレイ
2054 ディスプレイには 5 つのタイプがあります。
2055 即席 1 行インデントディスプレイ
2056 .Ql \&.D1
2057 、
2058 即席 1 行リテラルディスプレイ
2059 .Ql \&.Dl
2060 、それに
2061 ディスプレイ開始マクロ
2062 .Ql \&.Bd
2063 と
2064 ディスプレイ終了マクロ
2065 .Ql \&.Ed
2066 を使用する
2067 リテラルブロック、フィルブロックおよび凸凹ブロックです。
2068 .Pp
2069 .Bl -tag -width \&.Dlxx
2070 .It Li \&.D1
2071 (D-いち) インデントされたテキストを 1 行表示します。
2072 このマクロは解析されますが、呼び出し不可能です。
2073 .Pp
2074 .Dl Fl ldghfstru
2075 .Pp
2076 これは次の指定で生成されます:
2077 .Li \&.Dl Fl ldghfstru
2078 .It Li \&.Dl
2079 (D-エル) インデントされた
2080 .Em リテラル
2081 テキストを 1 行表示します。
2082 .Ql \&.Dl
2083 マクロの例は本ファイルの中に渡って使われています。
2084 これによって 1 行のテキストのインデント (表示) が可能になります。
2085 このマクロは解析され、他のマクロを認識することができますが、
2086 デフォルトのフォントは固定幅 (リテラル) にセットされています。
2087 しかしながら、呼び出しは不可能です。
2088 .Pp
2089 .Dl % ls -ldg /usr/local/bin
2090 .Pp
2091 これは次の指定で生成されます:
2092 .Li \&.Dl % ls -ldg /usr/local/bin .
2093 .It Li \&.Bd
2094 ディスプレイ開始です。
2095 .Ql \&.Bd
2096 によるディスプレイは
2097 .Ql \&.Ed
2098 マクロによって
2099 終了しなければなりません。
2100 ディスプレイはディスプレイ内およびリスト内で入れ子にすることができます。
2101 .Ql \&.Bd
2102 は以下の書式をとります。
2103 .Pp
2104 .Dl ".Bd ディスプレイタイプ [-offset オフセット値] [-compact]"
2105 .Pp
2106 ディスプレイタイプは以下の 4 つのタイプの内の 1 つでなければならず、
2107 インデント
2108 .Ql \&.Bd
2109 のオフセット値を指定することができます。
2110 .El
2111 .Pp
2112 .Bl -tag -width "file file_name  " -compact
2113 .It Fl ragged
2114 テキストのブロックをタイプされた通りに表示します。
2115 右マージン (と左マージン) のエッジは左に不揃いに寄せられます。
2116 .It Fl filled
2117 フィル (フォーマット) されたブロックを表示します。
2118 テキストのブロックがフォーマットされます
2119 (エッジは左非揃えではなく、フィルされます)。
2120 .It Fl literal
2121 リテラルなブロックを表示します。ソースコードや、単純にタブもしくは
2122 スペースで整えられたテキストで便利です。
2123 .It Fl file Ar ファイル名
2124 .Fl file
2125 フラグに続く名称のファイルが読み込まれ、表示されます。表示
2126 はリテラルなモードで行われ、タブは定幅文字 8 つ分に固定されますが、
2127 ファイル中のすべての
2128 .Xr troff/ Ns Nm \-mdoc
2129 コマンドは解釈されます。
2130 .It Fl offset Ar string
2131 .Fl offset
2132 が以下の文字列のいずれかとともに指定されていると、
2133 その文字列は次のテキストのブロックのインデントのレベルを示すものとして
2134 解釈されます。
2135 .Pp
2136 .Bl -tag -width indent-two -compact
2137 .It Ar left
2138 ブロックを現在の左マージンに揃えます。
2139 これは
2140 .Ql \&.Bd
2141 のデフォルトのモードです。
2142 .It Ar center
2143 ブロックを中央揃えにします。残念ながら現時点では、
2144 単にブロックの左側を仮想的な中央マージンに揃えるだけです。
2145 .It Ar indent
2146 デフォルトのインデント値もしくはタブの分だけインデントします。
2147 デフォルトのインデント値はディスプレイ
2148 .Ql \&.D1
2149 でも使われ、
2150 これら 2 つのタイプのディスプレイを使った場合、
2151 行が揃うことが保証されています。
2152 このインデントは通常 6n か約 2/3 インチ (定幅文字 6 つ分) です。
2153 .It Ar indent-two
2154 デフォルトのインデント値の 2 倍分インデントします。
2155 .It Ar right
2156 これはブロックをページの右端から約 2 インチ離して
2157 .Em 左
2158 揃えします。このマクロはちゃんと動作する必要があるのですが、
2159 .Xr troff
2160 ではまったくちゃんと動作してくれていません。
2161 .El
2162 .It .Ed
2163 ディスプレイ終了。
2164 .El
2165 .Ss フォントモード
2166 マニュアルページのテキストの見栄えを変更するマクロは 5 つあります。
2167 .Bl -tag -width \&.Emxx
2168 .It \&.Em
2169 テキストは
2170 .Ql \&.Em
2171 マクロで強調することができます。
2172 強調の場合、通常イタリック体のフォントが使われます。
2173 .Pp
2174 .Dl 使い方: .Em argument ... \*(Pu
2175 .Bl -tag -width "\&.Em vide infra ) ) ," -compact -offset 14n
2176 .It Li ".Em does not"
2177 .Em does not
2178 .It Li ".Em exceed 1024 ."
2179 .Em exceed 1024 .
2180 .It Li ".Em vide infra ) ) ,"
2181 .Em vide infra ) ),
2182 .El
2183 .Pp
2184 .Ql \&.Em
2185 マクロは解析され、呼び出し可能です。
2186 .Ql \&.Em
2187 を引数なしで呼び出すのはエラーです。
2188 .It \&.Li
2189 リテラルマクロ
2190 .Ql \&.Li
2191 は特殊文字や変数定数、その他タイプされた
2192 通りに表示する必要があるものに使用することができます。
2193 .Pp
2194 .Dl 使い方: .Li argument ... \*(Pu
2195 .Bl -tag -width "\&.Li cntrl-D ) ," -compact -offset 14n
2196 .It Li \&.Li \een
2197 .Li \en
2198 .It Li \&.Li M1 M2 M3\ ;
2199 .Li M1 M2 M3 ;
2200 .It Li \&.Li cntrl-D\ )\ ,
2201 .Li cntrl-D ) ,
2202 .It Li \&.Li 1024\ ...
2203 .Li 1024 ...
2204 .El
2205 .Pp
2206 .Ql \&.Li
2207 マクロは解析され、呼び出し可能です。
2208 .It \&.Sy
2209 シンボリック体強調マクロはシンボリックの意味でも
2210 伝統的な英語の使いかたにおいても、
2211 通常はボールドマクロとなっています。
2212 .Pp
2213 .Dl 使い方: .Sy symbol ... \*(Pu
2214 .Bl -tag -width "\&.Sy Important Noticex" -compact -offset 14n
2215 .It Li \&.Sy Important Notice
2216 .Sy Important Notice
2217 .Pp
2218 .Ql \&.Sy
2219 マクロは解析され、呼び出し可能です。
2220 .Ql \&.Sy
2221 の引数は引用符で囲むことができます。
2222 .El
2223 .It Li \&.Bf
2224 フォントモード開始。
2225 フォントモード
2226 .Ql \&.Bf
2227 は
2228 .Ql \&.Ef
2229 マクロで
2230 終了しなければなりません。
2231 フォントモードは他のフォントモードと入れ子にすることができます。
2232 .Ql \&.Bf
2233 は次の構文を取ります。
2234 .Pp
2235 .Dl ".Bf font-mode"
2236 .Pp
2237 font-mode は以下の 3 つのタイプのうちのいずれかでなければなりません。
2238 .Pp
2239 .Bl -tag -width "file file_name  " -compact
2240 .It Sy \&Em | Fl emphasis
2241 強調モード。
2242 .Ql \&.Em
2243 マクロがテキストブロック全体に使われているのと同様です。
2244 .It Sy \&Li | Fl literal
2245 リテラルモード。
2246 .Ql \&.Li
2247 マクロがテキストブロック全体に使われているのと同様です。
2248 .It Sy \&Sy | Fl symbolic
2249 シンボリックモード。
2250 .Ql \&.Sy
2251 マクロがテキストブロック全体に使われているのと同様です。
2252 .El
2253 .It .Ef
2254 フォントモードの終了。
2255 .El
2256 .Ss タグ付きリストと列
2257 リスト開始マクロ
2258 .Ql ".Bl"
2259 で開始されるリストにはいくつかのタイプが
2260 あります。リスト中の項目は項目マクロ
2261 .Ql ".It"
2262 で指定され、各リスト
2263 は
2264 .Ql ".El"
2265 マクロで終了しなければなりません。リストはリスト自身や
2266 ディスプレイの中で入れ子にすることができます。列はリストの中で使うこと
2267 ができますが、リストが列の中で使えるかどうかは検証されていません。
2268 .Pp
2269 さらに、タグの幅、リストのオフセット、コンパクトさ(項目間の空白行が
2270 許されているかどうか) のような、いくつかのリストの属性を指定することが
2271 できます。本ドキュメントのほとんどはタグ
2272 .Pq Fl tag
2273 スタイルリストで
2274 フォーマットされています。各種リストタイプは、調子を変えるために
2275 オーバーハング
2276 .Pq Fl ohang
2277 でリストしました。
2278 このリストのタイプは
2279 .Tn TeX
2280 のユーザに非常に人気のあるものですが、
2281 tag リストで構成されたページを何ページも読んだ後には幾分変に見える
2282 でしょう。以下のリストタイプを
2283 .Ql ".Bl"
2284 で使うことができます。
2285 .Pp
2286 .Bl -ohang -compact
2287 .It Fl bullet
2288 .It Fl item
2289 .It Fl enum
2290 これら 3 つは最も単純なリストのタイプです。
2291 一旦
2292 .Ql ".Bl"
2293 マクロが与えられると、リスト中の項目は
2294 単に
2295 .Ql ".It"
2296 マクロによってのみ構成される行で指定されます。
2297 例として、簡単な列挙リストのソーステキストは、このようになります。
2298 .Bd -literal -offset indent-two
2299 \&.Bl -enum -compact
2300 \&.It
2301 \&ひとつめはここ。
2302 \&.It
2303 \&そしてふたつめ。
2304 \&.It
2305 \&最後にみっつめはここ。
2306 \&.El
2307 .Ed
2308 .El
2309 .Pp
2310 これらの結果は以下のようになります。
2311 .Pp
2312 .Bl -enum -offset indent-two -compact
2313 .It
2314 ひとつめはここ。
2315 .It
2316 そしてふたつめ。
2317 .It
2318 最後にみっつめはここ。
2319 .El
2320 .Pp
2321 簡単な bullet リスト構成の例を示します。
2322 .Bd -literal -offset indent-two
2323 \&.Bl -bullet -compact
2324 \&.It
2325 \&ひとつめの bullet。
2326 \&.It
2327 \&これはふたつめの bullet。
2328 \&.El
2329 .Ed
2330 .Pp
2331 これは以下のような結果になります。
2332 .Bl -bullet -offset indent-two -compact
2333 .It
2334 ひとつめの bullet。
2335 .It
2336 これはふたつめの bullet。
2337 .El
2338 .Pp
2339 .Bl -ohang -compact
2340 .It Fl tag
2341 .It Fl diag
2342 .It Fl hang
2343 .It Fl ohang
2344 .It Fl inset
2345 これらのリストタイプは
2346 .Ql \&.It
2347 マクロによって指定されている引数
2348 からラベルを生成します。
2349 そして、
2350 .Em inset
2351 では、次のテキストへそのラベルを挿入します。
2352 .Em hang
2353 では、次のテキストをラベルの位置へインデントします。
2354 .Em ohang
2355 (オーバーハング) では、次のテキストをラベルの位置に
2356 ぶら下げ、インデントしません。
2357 .Em tag
2358 では、タグつきテキストの形式にします。ちなみに上のリストは
2359 .Ql \&Fl ohang
2360 リストタイプで構成されています。
2361 .Ql \&.It
2362 マクロは inset, hang, tag のリストタイプでのみ解析され、
2363 呼び出し不可能です。以下に inset ラベルの例を示します。
2364 .El
2365 .Bl -inset -offset indent
2366 .It Em Tag
2367 tag リスト (tag 段落とも呼ばれる) は、
2368 Berkely マニュアルで使われているリストのうち最も一般的なタイプです。
2369 .It Em Diag
2370 診断リストはセクション 4 の診断リストを生成するもので、
2371 呼び出し可能なマクロが無視されることを除き、inset リストと似ています。
2372 .It Em Hang
2373 hang ラベルは好みの問題です。
2374 .It Em Ohang
2375 ohang ラベルはスペースに制限がある時に便利です。
2376 .It Em Inset
2377 inset ラベルは段落のブロックを制御するのに便利で、
2378 .Nm \-mdoc
2379 マニュアルを他の形式に変換する時に役立ちます。
2380 .El
2381 .Pp
2382 上の例を生成したソーステキストはこうなっています。
2383 .Bd -literal -offset indent
2384 \&.Bl -inset -offset indent
2385 \&.It Em Tag
2386 \&tag リスト (tag 段落とも呼ばれる) は、
2387 \&Berkely マニュアルで使われているリストのうち最も一般的なタイプです。
2388 \&.It Em Diag
2389 \&診断リストはセクション 4 の診断リストを生成するもので、
2390 \&呼び出し可能なマクロが無視されることを除き、inset リストと似ています。
2391 \&.It Em Hang
2392 \&hang ラベルは好みの問題です。
2393 \&.It Em Ohang
2394 \&ohang ラベルはスペースに制限がある時に便利です。
2395 \&.It Em Inset
2396 \&inset ラベルは段落のブロックを制御するのに便利で、
2397 \&.Nm \-mdoc
2398 \&マニュアルを他の形式に変換する時に役立ちます。
2399 \&.El
2400 .Ed
2401 .Pp
2402 以下は 2 つの項目を持つ hang リストです。
2403 .Bl -hang -offset indent
2404 .It Em Hanged
2405 ラベルがラベルの幅より小さいときには、
2406 ラベルは tag リストと同じようになります。
2407 .It Em 長い hang リストラベル
2408 は、tag 段落のラベルとは異なり、
2409 段落の中に埋め込まれます。
2410 .El
2411 .Pp
2412 これを生成している元のテキストは以下の通りです。
2413 .Bd -literal -offset indent
2414 \&.Bl -hang -offset indent
2415 \&.It Em Hanged
2416 \&ラベルがラベルの幅より小さいときには、
2417 \&ラベルは tag リストと同じようになります。
2418 \&.It Em 長い hang リストラベル
2419 \&は、tag 段落のラベルとは異なり、
2420 \&段落の中に埋め込まれます。
2421 \&.El
2422 .Ed
2423 .Pp
2424 タグ幅を制御するためのオプションの幅指定を使ったタグつきリストは
2425 以下の通りです。
2426 .Pp
2427 .Bl -tag -width PAGEIN -compact -offset indent
2428 .It SL
2429 プロセスが sleep している時間 (ブロックされた秒数)
2430 .It PAGEIN
2431 そのプロセスによるコアにロードされていないページへの参照による
2432 ディスク
2433 .Tn I/O
2434 の回数
2435 .It UID
2436 プロセスの所有者の数字表記によるユーザID
2437 .It PPID
2438 親プロセスの数字表記によるID、プロセスの優先度
2439 (割り込み不可のウエイトであるときには非正値)
2440 .El
2441 .Pp
2442 The raw text:
2443 .Bd -literal -offset indent
2444 \&.Bl -tag -width "PAGEIN" -compact -offset indent
2445 \&.It SL
2446 \&プロセスが sleep している時間 (ブロックされた秒数)
2447 \&.It PAGEIN
2448 \&そのプロセスによるコアにロードされていないページへの参照によるディスク
2449 \&.Tn I/O
2450 \&の回数
2451 \&.It UID
2452 \&プロセスの所有者の数字表記によるユーザID
2453 \&.It PPID
2454 \&親プロセスの数字表記によるID、プロセスの優先度
2455 \&(割り込み不可のウエイトであるときには非正値)
2456 \&.El
2457 .Ed
2458 .Pp
2459 幅指定として以下のものを使うことができます。
2460 .Bl -tag -width Ar -offset indent
2461 .It Fl width Ar \&Fl
2462 そのフラグでのデフォルトの幅を指定します。すべての呼び出し可能なマクロ
2463 は各々デフォルトの幅の値を持っています。現在、
2464 .Ql \&.Fl
2465 の値は定幅
2466 文字 10 個分、もしくは約 5/6 インチとなっています。
2467 .It Fl width Ar 24n
2468 定幅文字 24 個分の幅、もしくは約 2 インチの幅をセットします。
2469 これが正しく動作するには
2470 .Ql n
2471 が必ず必要となります。
2472 .It Fl width Ar ENAMETOOLONG
2473 指定された文字列の固定長に幅をセットします。
2474 .It Fl width Ar "\*qint mkfifo\*q"
2475 これも、指定された文字列の固定長に幅をセットします。
2476 .El
2477 .Pp
2478 タグつきリストタイプで幅が指定されていないと、
2479 .Ql \&.It
2480 が最初に
2481 起動された時に適した幅を決定することが試みられます。
2482 .Ql ".It"
2483 の
2484 最初の引数が呼び出し可能なマクロであれば、そのマクロのデフォルトの幅が
2485 そのマクロ名が幅として指定されたように使用されます。しかしながら、その
2486 リスト中に他の項目が別の呼び出し可能なマクロ名で与えられていると、
2487 新しく入れ子となったリストとして処理されます。
2488 .Sh 定義済みの文字列
2489 以下の文字列はあらかじめ定義されているものであり、troff の文字列解釈
2490 シーケンス
2491 .Ql \&\e*(xx
2492 もしくは
2493 .Ql \&\e*x
2494 を前に伴って使われます。
2495 ここで、
2496 .Em xx
2497 もしくは
2498 .Em x
2499 は定義されている文字列の名称です。
2500 解釈シーケンスはテキストのどこでも使うことができます。
2501 .Pp
2502 .Bl -column "String " "Nroff " "Troff " -offset indent
2503 .It Sy "文字列       Nroff   Troff"
2504 .It Li <= Ta \&<\&= Ta \*(<=
2505 .It Li >= Ta \&>\&= Ta \*(>=
2506 .It Li Rq Ta '' Ta \*(Rq
2507 .It Li Lq Ta `` Ta \*(Lq
2508 .It Li ua Ta ^ Ta \*(ua
2509 .It Li aa Ta ' Ta \*(aa
2510 .It Li ga Ta \` Ta \*(ga
2511 .\" .It Li "sL" Ta ` Ta \*(sL
2512 .\" .It Li "sR" Ta ' Ta \*(sR
2513 .It Li q Ta \(dq Ta \*q
2514 .It Li Pi Ta pi Ta \*(Pi
2515 .It Li Ne Ta != Ta \*(Ne
2516 .It Li Le Ta <= Ta \*(Le
2517 .It Li Ge Ta >= Ta \*(Ge
2518 .It Li Lt Ta < Ta \*(Gt
2519 .It Li Gt Ta > Ta \*(Lt
2520 .It Li Pm Ta +- Ta \*(Pm
2521 .It Li If Ta infinity Ta \*(If
2522 .It Li Na Ta \fINaN\fP Ta \*(Na
2523 .It Li Ba Ta \&| Ta \*(Ba
2524 .El
2525 .Pp
2526 .Sy 注 :
2527 .Ql q
2528 の名称がつけられている文字列は、
2529 1 文字であるため
2530 .Ql \e*q
2531 と書かなければなりません。
2532 .Sh 診断
2533 .Nm \-mdoc
2534 は限られたデバッグ機能しか持っていませんが、
2535 引数名と内部レジスタやマクロ名との衝突のような
2536 潜在的なエラーを検出するのに役立ちます。 (A って何?)
2537 レジスタは
2538 .Xr troff
2539 での演算用記憶クラスであり、
2540 1 文字か 2 文字の名称がついています。
2541 .Xr troff
2542 と
2543 .Xr ditroff
2544 での
2545 .Nm \-mdoc
2546 のすべての内部レジスタは
2547 .Ql \&Ar
2548 のように2 文字からなる <大文字><小文字> の形式か、
2549 .Ql \&aR
2550 のように <小文字><大文字> の形式か、
2551 .Ql \&C\&1
2552 のように <大文字もしくは小文字><数字>
2553 の形式を取ります。
2554 さらに混乱することに、
2555 .Xr troff
2556 はそれ自身の内部レジスタを持ち、
2557 それらすべては小文字 2 文字か、ドットに文字もしくはメタ文字が続く形式を取ります。
2558 紹介例の 1 つに、エスケープシーケンス
2559 .Ql \e&
2560 でマクロ名を
2561 解釈させない方法がありました。これは内部レジスタ名にも有効です。
2562 .Pp
2563 .\" Every callable macro name has a corresponding register
2564 .\" of the same name (<upper_case><lower_case>).
2565 .\" There are also specific registers which have
2566 .\" been used for stacks and arrays and are listed in the
2567 .\" .Sx Appendix .
2568 .\" .Bd -ragged -offset 4n
2569 .\" [A-Z][a-z]  registers corresponding to macro names (example ``Ar'')
2570 .\" [a-z][A-Z]  registers corresponding to macro names (example ``aR'')
2571 .\" C[0-9]              argument types (example C1)
2572 .\" O[0-9]              offset stack (displays)
2573 .\" h[0-9]              horizontal spacing stack (lists)
2574 .\" o[0-9]              offset (stack) (lists)
2575 .\" t[0-9]              tag stack (lists)
2576 .\" v[0-9]              vertical spacing stack (lists)
2577 .\" w[0-9]              width tag/label stack
2578 .\" .Ed
2579 .\" .Pp
2580 エスケープされていないレジスタ名が引数リストに指定されると、
2581 予期できない振舞いとなります。
2582 一般的には、テキストのかなり大きな部分が出力されるべきところに
2583 出力されないとか、リストのタグのような小さな文字列が消えてしまうとか、
2584 引数リストの中の引数のタイプが間違って解釈されるとかいうことが、起こり得ます。
2585 きっとあなたのお母さんは、あなたにこんな面倒なことを覚えるようにとは
2586 考えていないでしょう。
2587 そこで、与えられた引数が有効か無効かを判断する方法があります。
2588
2589 そんなときには、
2590 .Ql \&.Db
2591 (デバッグ) マクロによってほとんどのマクロ
2592 の引数リストがどう解釈されるかを表示することができます。
2593 .Ql \&.Pp
2594 (段落) マクロのようなマクロはデバッグ情報を含んでいません。呼び出し可能
2595 なマクロはすべてデバッグ情報を含んでおり、疑いがある場合はいつでも
2596 .Ql \&.Db
2597 マクロをオンにすることを強くお勧めします。
2598 .Pp
2599 .Dl 使い方: \&.Db [on | off]
2600 .Pp
2601 以下の例では、問題が故意に発生するようにされた部分の上と下で
2602 デバッグマクロが指定されています
2603 (フラグ引数
2604 .Ql \&aC
2605 は正しく動作するためには
2606 .Ql \e&aC
2607 でなければなりません)。
2608 .Bd -literal -offset indent
2609 \&.Db on
2610 \&.Op Fl aC Ar file )
2611 \&.Db off
2612 .Ed
2613 .Pp
2614 この結果の出力は以下の通りです。
2615 .Bd -literal -offset indent
2616 DEBUGGING ON
2617 DEBUG(argv) MACRO: `.Op'  Line #: 2
2618         Argc: 1  Argv: `Fl'  Length: 2
2619         Space: `'  Class: Executable
2620         Argc: 2  Argv: `aC'  Length: 2
2621         Space: `'  Class: Executable
2622         Argc: 3  Argv: `Ar'  Length: 2
2623         Space: `'  Class: Executable
2624         Argc: 4  Argv: `file'  Length: 4
2625         Space: ` '  Class: String
2626         Argc: 5  Argv: `)'  Length: 1
2627         Space: ` '  Class: Closing Punctuation or suffix
2628         MACRO REQUEST: .Op Fl aC Ar file )
2629 DEBUGGING OFF
2630 .Ed
2631 .Pp
2632 この情報の最初の行では呼び出されているマクロの名称が出力されています。
2633 ここでは
2634 .Ql \&.Op
2635 とそれが現れた行番号が表示されています。
2636 複数のファイルが処理されている場合
2637 (特にテキストが他のファイルからインクルードされている場合)、
2638 行番号は正しくないでしょう。
2639 ファイルが 1 つだけの場合には正しい行番号が出力されます。
2640 2 番目の行では引数の個数と引数
2641 .Pq Ql \&Fl
2642 とその長さが
2643 出力されています。引数の長さが 2 文字であれば、
2644 その引数が実行可能
2645 (ゼロでない値を含むすべてのレジスタは実行可能なように見えます)
2646 かどうかテストされます。
2647 3 番目の行ではそのクラスで指定されているスペースとクラスタイプが
2648 出力されています。
2649 ここでの問題は引数 aC が実行不可能でなければならないことです。
2650 クラスの 4 つのタイプは文字列、実行可能、閉じる句読点、開く句読点です。
2651 最後の行では引数リスト全体が読み込まれた通りに表示されています。
2652 次の例では問題の原因となっている
2653 .Ql \&aC
2654 がエスケープされています。
2655 .Bd -literal -offset indent
2656 \&.Db on
2657 \&.Em An escaped \e&aC
2658 \&.Db off
2659 .Ed
2660 .Bd -literal -offset indent
2661 DEBUGGING ON
2662 DEBUG(fargv) MACRO: `.Em'  Line #: 2
2663         Argc: 1  Argv: `An'  Length: 2
2664         Space: ` '  Class: String
2665         Argc: 2  Argv: `escaped'  Length: 7
2666         Space: ` '  Class: String
2667         Argc: 3  Argv: `aC'  Length: 2
2668         Space: ` '  Class: String
2669         MACRO REQUEST: .Em An escaped &aC
2670 DEBUGGING OFF
2671 .Ed
2672 .Pp
2673 .Ql \e&
2674 シーケンスは長さが 0 となるために
2675 引数
2676 .Ql \e&aC
2677 は先の例と同様に長さ 2 と表示されています。
2678 しかし、
2679 .Ql \e&aC
2680 という名称のレジスタが見つからず、
2681 タイプは文字列と判断されています。
2682 .Pp
2683 この他の診断は使用方法を報告するものであり、
2684 それ自身が説明を含んでいます。
2685 .Sh GROFF, TROFF, NROFF
2686 .Nm \-mdoc
2687 パッケージは
2688 .Xr groff
2689 との互換モードは
2690 必要ではありません。
2691 .Pp
2692 このパッケージでは改ページと、
2693 .Xr nroff
2694 で改ページ時に通常挿入
2695 されるヘッダとフッタは禁止されており、マニュアルをオンラインで効率良く
2696 見ることができるようになっています。現在の所、
2697 .Fl T Ns Ar ascii
2698 が
2699 指定された
2700 .Xr groff
2701 はページ内容の無いファイル末の残りの部分まで
2702 出力します。改ページを禁止することによって
2703 .Xr nroff
2704 による出力は
2705 ハードコピーには適さないものとなっています。サイト依存のスタイル
2706 ファイル
2707 .Pa /usr/src/share/tmac/doc-nroff
2708 において 0 にセットする
2709 ことができる
2710 .Ql \&cR
2711 の名称を持つレジスタが古いスタイルの振る舞い
2712 を実現するために用意されています。
2713 .Sh ファイル
2714 .Bl -tag -width /usr/share/man0/template.doc -compact
2715 .It Pa /usr/share/tmac/doc.tmac
2716 マニュアルマクロパッケージ
2717 .It Pa /usr/share/misc/mdoc.template
2718 man ページを書くためのテンプレート
2719 .It Pa /usr/share/examples/mdoc/*
2720 man ページのいくつかの例
2721 .El
2722 .Sh バグ
2723 フラグ引き数のダッシュが意図せずハイフンにより折り返しになるバグは
2724 まだ修正されておらず、
2725 .Sx DESCRIPTION
2726 セクションでときどき
2727 意図しない動作 (ハイフンでの改行) が起こることがある。
2728 .Pp
2729 あらかじめ定義されている文字列は文書において宣言されていません。
2730 .Pp
2731 セクション 3f はヘッダルーチンには追加されていません。
2732 .Pp
2733 .Ql \&.Nm
2734 フォントは
2735 .Sx 名前
2736 セクションにおいて
2737 変更されるべきです。
2738 .Pp
2739 .Ql \&.Fn
2740 は分割されるのを防止するために、行の長さが短すぎないか
2741 どうかをチェックする必要があります。ときどき、最後の括弧が分割される
2742 ことがあり、行がフィルモードであるときには全くおかしな結果になること
2743 があります。
2744 .Pp
2745 nroff 使用時に、(最初のヘッダとフッタ以外の) 改ページ時のヘッダと
2746 フッタの挿入を行わないようにするのに使用される命令によって、
2747 ときどき見るに耐えない部分的な行詰め (や空行) がページの末尾に
2748 発生する場合がある。
2749 .Pp
2750 .\" Note what happens if the parameter list overlaps a newline
2751 .\" boundary.
2752 .\" to make sure a line boundary is crossed:
2753 .\" .Bd -literal
2754 .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
2755 .\" .Ed
2756 .\" .Pp
2757 .\" produces, nudge nudge,
2758 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
2759 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
2760 .\" nudge
2761 .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
2762 .\" .Pp
2763 .\" If double quotes are used, for example:
2764 .\" .Bd -literal
2765 .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
2766 .\" .Ed
2767 .\" .Pp
2768 .\" produces, nudge nudge,
2769 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
2770 .\" nudge
2771 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
2772 .\" nudge
2773 .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
2774 .\" .Pp
2775 .\" Not a pretty sight...
2776 .\" In a paragraph, a long parameter containing unpaddable spaces as
2777 .\" in the former example will cause
2778 .\" .Xr troff
2779 .\" to break the line and spread
2780 .\" the remaining words out.
2781 .\" The latter example will adjust nicely to
2782 .\" justified margins, but may break in between an argument and its
2783 .\" declaration.
2784 .\" In
2785 .\" .Xr nroff
2786 .\" the right margin adjustment is normally ragged and the problem is
2787 .\" not as severe.
2788 リストマクロとディスプレイマクロはキープを行いませんが、
2789 これはキープを行うべきです。
2790 .Sh 関連項目
2791 .Xr man 1 ,
2792 .Xr troff 1 ,
2793 .Xr groff_mdoc 7 ,
2794 .Xr mdoc 7
2795 .Sh この文書について
2796 This page is part of release 3.53 of the Linux
2797 .Em man-pages
2798 project.  A
2799 description of the project, and information about reporting bugs, can be
2800 found at \%http://www.kernel.org/doc/man\-pages/.