release/man7/mdoc.samples.7

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