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