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