groff_mdoc(7) FreeBSD 一般コマンドマニュアル

groff_mdoc

前のページ 上に戻る 次のページ

groff_mdoc




解説

     GNU troff(1) 用の コンテントベースでかつ 領域ベースな整形用パッケージであ
     る -mdoc マクロパッケージを使って UNIX マニュアルページを書くための完全な
     リファレンスです。前身である -man(7) パッケージは、フォントの操作や他の写
     植方法の詳細は個々の作者に任せ、ページのレイアウトを取り扱ってきました。
     -mdoc では、ページレイアウトマクロはタイトル、セクションのヘッダ、ディス
     プレイ、リストのマクロからなる ページ構造領域を形成しています。本質的にこ
     れらの要素は整形されたページにおけるテキストの物理的位置に影響を与えま
     す。ページ構造領域に加え、さらに マニュアル領域および 一般テキスト領域の
     2 つの領域があります。一般テキスト領域は、テキストの一部をクォートしたり
     強調したりといったような作業を実行するマクロとして定義されています。マ
     ニュアル領域はコマンドやルーチン、それに UNIX の関連ファイルを記述するた
     めの日常使用されるインフォーマルな言葉のサブセットであるマクロとして定義
     されています。マニュアル領域のマクロはコマンド名、コマンド行の引数とオプ
     ション、関数名、関数のパラメータ、パス名、変数名、他のマニュアルページへ
     のクロスリファレンスなどを扱います。これらの領域の項目は作者とマニュアル
     ページの将来のユーザの両者にとって価値のあるものです。マニュアル間で一貫
     性を高めることによって将来のドキュメントツールへの移行が容易になることが
     期待されます。

     UNIX マニュアルページ全体を通して、マニュアルのエントリは単純にマニュアル
     ページ (a man page) とみなされます。これは実際のページ数と関係ありません
     し、性差別をする意図もありません。


さあ、始めよう

     このドキュメントの残りの部分で説明されている題材は以下のような構成になっ
     ています。

           1.   TROFF に特有な表現
                マクロの使用方法
                引数に空白文字を指定する
                行末の空白文字
                特殊文字のエスケープ
                その他の注意点

           2.   マニュアルページのテンプレート

           3.   使用法

           4.   タイトルマクロ

           5.   マニュアル領域および一般テキスト領域の紹介
                この名前には何が...
                一般的な構文

           6.   マニュアル領域
                アドレス
                作者名
                引数
                コンフィギュレーション宣言 (セクション 4 のみ)
                コマンド修飾子
                オプション
                パス名
                標準
                変数の型
                変数
                マニュアルページのクロスリファレンス

           7.   一般テキスト領域
                AT&T マクロ
                BSD マクロ
                NetBSD マクロ
                FreeBSD マクロ
                OpenBSD マクロ
                BSD/OS マクロ
                UNIX マクロ
                強調マクロ
                フォントモード
                囲い/クォート マクロ
                無操作もしくは通常テキストマクロ
                空白なしマクロ
                セクションのクロスリファレンス
                記号
                数式記号
                参考文献と引用
                商標名 (頭字語とタイプ名)
                拡張引数

           8.   ページ構造領域
                セクションヘッダ
                サブセクションヘッダ
                段落と行スペース
                キープ
                例示とディスプレイ
                リストとカラム

           9.   その他のマクロ

           10.  定義済みの文字列

           11.  診断

           12.  GROFF, TROFF および NROFF を使用した整形

           13.  関連ファイル

           14.  関連項目

           15.  バグ


TROFF に特有な表現

     -mdoc パッケージは、マニュアルページを記述するプロセスを簡単にすることを
     目的としています。 -mdoc を使うために GNU troff(1) のゴタゴタした詳細を学
     シーケンス `\&' を指定します。 `\&' は文字通りスペース幅が 0 として解釈さ
     れ、出力には現れません。

     一般的に GNU troff(1) マクロは取り得る引数の数に制限はありません (9 つ以
     上の引数を扱うことのできない他のバージョンの troff とは違います)。限られ
     た場合ではありますが、引数を次の行に続けたり、拡張したりすることができま
     す (後述の 拡張引数のセクションを参照)。ほとんどすべてのマクロで引用符に
     囲まれた引数を扱うことができます (後述の 引数に空白文字を指定するのセク
     ションを参照)。

     -mdoc での一般テキスト領域とマニュアル領域のほとんどのマクロは、呼び出し
     可能なマクロ名を決定するためにその引数のリストが 構文解析されるという点で
     特別なものです。これはつまり、一般テキスト領域またはマニュアル領域のマク
     ロ名に一致し、かつ、呼び出し可能であると判断された引数リスト中の引数は、
     処理される時に実行されるか、もしくは呼び出されるということです。この場
     合、引数がマクロの名前であっても `.' (ドット) で前置されません。このよう
     にしてたくさんのマクロを入れ子にすることができます。例えばオプションマク
     ロ `.Op' はフラグマクロおよび引数マクロ `Fl' と `Ar' を 呼び出して、オプ
     ションのフラグを引数とともに指定することができます:

           [-s bytes]  は `.Op Fl s Ar bytes' で生成されます。

     文字列がマクロ名と解釈されないようにするには、その文字列の前にエスケープ
     シーケンス `\&' を指定します。

           [Fl s Ar bytes]  は `.Op \&Fl s \&Ar bytes' で生成されます。

     ここで文字列 `Fl' と `Ar' はマクロとして解釈されていません。このドキュメ
     ントを通じて、呼び出し可能な引数を調べるために引数リストが構文解析される
     マクロは 構文解析されるマクロとして参照し、引数リストから呼び出されること
     ができるマクロは 呼び出し可能なマクロとして参照します。 -mdoc のマクロは
     ほとんどすべてが構文解析されるのですから、これは技術的には 適当でない表現
     ですが、常にマクロを「呼び出し可能である」とか「他のマクロを呼び出すこと
     ができる」と表現するのは面倒なことであるため、「構文解析される」という用
     語を使います。

   B>引B>数B>にB>空B>白B>文B>字B>をB>指B>定B>すB>る
     1 つ以上の空白文字を含む文字列を引数として指定したい場合があります。引数
     リスト中の要素が特定の並びをしていることを期待しているマクロに引数を指定
     する時に必要になることがあります。さらに、こうすると -mdoc が速く実行され
     るようになるのです。例えば、関数マクロ `.Fn' では第 1 引数は関数名であ
     り、残りの引数が関数のパラメータであると想定されています。 ANSI C では、
     関数のパラメータ宣言を括弧で囲まれたパラメータリスト中に明示することを規
     定しているので、各パラメータは最低でも 2 語の文字列となります。例えば、
     int foo のようになります。

     空白を含む引数を指定するには 2 通りの方法があります。 1 つは、空白を含む
     文字列を渡すのに、固定の空白、つまりパディングされない空白文字 `\ ' を使
     う方法です。すなわち、空白の前にエスケープ文字 `\' を指定します。この方法
     はどのマクロでも使うことができますが、1 行が長くなり過ぎたテキストを調整
     するときの邪魔になるという副作用があります。 troff では、固定の空白は他の
     印刷可能な文字と同様に扱われ、通常期待されるようにその箇所で文字列を空白
     は引数が 3 つであるとみなし、その結果は

           fetch(char, *str)

     となります。

   B>行B>末B>のB>空B>白B>文B>字
     Troff は行末に空白文字があると混乱してしまうことがあります。 <空白><行末>
     の文字の並びからすべての空白文字を取り除くのは良い予防策です。どうしても
     行末に空白文字をおく必要性が出てきた場合は、パディングされない空白とエス
     ケープ文字 `\&' を使用することによって対応できます。例えば、 `string\ \&'
     のようにします。

   B>特B>殊B>文B>字B>のB>エB>スB>ケB>ーB>プ
     改行 `\n' のような特殊文字は、バックスラッシュを保存するために `\' を
     `\e' で置き換え (たとえば `\en' とする) て扱います。

   B>そB>のB>他B>のB>注B>意I</I>点
     表示領域外で空の入力行が見つかった場合には警告が発生します (後述)。代わり
     に `.sp' を使用してください ( -mdoc マクロを使用して、低レベルコマンドを
     使用しないようにするとずっと良いです)。

     先頭に空白を置くと行分割が生じ、そのまま出力されてしまいます。可能ならば
     こうなることを避けてください。同様に、通常のテキスト行において単語間に 2
     つ以上の空白文字を使用しないでください。これは、他のテキストフォーマッタ
     とは対照的です。空白文字を 2 つ以上置いても 1 つの空白文字に 置き換わりま
     せん。

     引数として `"' を直接渡すことはできません。代わりに `\*[q]' (あるいは
     `\*q') を使用してください。

     デフォルトでは、 troff(1) は文を終了させる句読点の後に空白文字を 2 つ挿入
     します。つまり、 `)' あるいは `'' などの文字はそのまま扱われ、文の終了に
     は影響を与えません。この動作を変更するには、ドットの前あるいは後に `\&'
     を挿入してください。

           The
           .Ql .
           character.
           .Pp
           The
           .Ql \&.
           character.
           .Pp
           .No test .
           test
           .Pp
           .No test.
           test

     は、


     マニュアルページのソースファイル中のコメントは、独立した行では `.\"' 、何
     らかの入力があった後では `\"' を、あるいはどのような場所でも使いたい場合
     は `\#' を使うことができます (後者は GNU troff(1) 拡張です)。このような行
     の残りの部分は無視されます。


マニュアルページのテンプレート

     マニュアルページの中身は次のような基本的なテンプレートから簡単に作成でき
     ます。

           .\" 以下の項目はすべてのマニュアルページで必要な項目です。
           .Dd 月 日, 年
           .Os [オペレーティングシステム] [バージョン/リリース]
           .Dt ドキュメントタイトル [セクション番号] [アーキテクチャ/ボリューム]
           .Sh NAME
           .Nm 名称
           .Nd 名称についての 1 行での説明
           .\" 次の項目はセクション 2, 3 でのみ必要なものです。
           .\" .Sh LIBRARY
           .Sh SYNOPSIS
           .Sh DESCRIPTION
           .\" 以下の項目については、必要に応じてコメントをはずして使用してく
           .\" ださい。
           .\" .Sh IMPLEMENTATION NOTES
           .\" この次の項目はセクション 2, 3, 9 でのみ必要な、関数の
           .\" 戻り値です。
           .\" .Sh RETURN VALUES
           .\" 次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。
           .\" .Sh ENVIRONMENT
           .\" .Sh FILES
           .\" .Sh EXAMPLES
           .\" 次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。
           .\"     ((シェルへの)コマンドの戻り値と
           .\"       fprintf/stderr タイプの診断です)
           .\" .Sh DIAGNOSTICS
           .\" .Sh COMPATIBILITY
           .\" 次の項目はセクション 2, 3, 9 でのみ必要な、
           .\"     エラーハンドリングとシグナルハンドリングです。
           .\" .Sh ERRORS
           .\" .Sh SEE ALSO
           .\" .Sh STANDARDS
           .\" .Sh HISTORY
           .\" .Sh AUTHORS
           .\" .Sh BUGS

     このテンプレートにおける最初の項目はマクロ `.Dd', `.Os', および `.Dt' で
     あり、それぞれドキュメントの日付、マニュアルページもしくは題材となってい
     るソースの開発や変更の対象となったオペレーティングシステム、そしてマニュ
     アルページのタイトルを属するマニュアルのセクション番号とともに ( 大文字で
     ) 指定したもの、となっています。これらのマクロはそのページを識別するもの
     であり、後述の タイトルマクロで解説されます。


           .Xx <foo> {bar1 | bar2} [-test1 [-test2 | -test3]] ...

     とくに明示しない限り、すべてのマクロは構文解析され、呼び出し可能なもので
     す。

     大部分のマクロはデフォルトの幅の値を持っており、これを `.Bl' および `.Bd'
     マクロ用にラベル width (-width) あるいは offset (-offset) を指定するのに
     使用することができます。 -mdoc パッケージのローカルな変更に依存することの
     ないように、このとても曖昧な機能は使わないことを推奨します。


タイトルマクロ

     タイトルマクロはページ構造領域の一部ですが、マニュアルページを昨日書き始
     めようと思ったという人のために、最初に、他のとは別に記述されています。 3
     つのヘッダマクロでドキュメントまたはマニュアルページのタイトル、オペレー
     ティングシステム、および原著の日付を指定します。これらのマクロはドキュメ
     ントの最初で一度だけ呼び出されるもので、ヘッダとフッタを構成するためだけ
     に使用されます。

     .Dt [<ドキュメントタイトル>] [<セクション番号>] [<ボリューム>]
             ドキュメントタイトルはマニュアルページの主題であり、 troff の制限
             により 大文字でなければいけません。省略された場合、 `UNTITLED' が
             使われます。セクション番号は 1, ..., 9 の範囲の番号もしくは
             `unass', `draft', `paper' のいずれかを取ることができます。セク
             ション番号が指定されており、ボリューム名が与えられていない場合に
             は、デフォルトのボリューム名が使用されます。

             FreeBSD 4.4 では、次のセクションが定義されています:

                   1        FreeBSD General Commands Manual
                   2        FreeBSD System Calls Manual
                   3        FreeBSD Library Functions Manual
                   4        FreeBSD Kernel Interfaces Manual
                   5        FreeBSD File Formats Manual
                   6        FreeBSD Games Manual
                   7        FreeBSD Miscellaneous Information Manual
                   8        FreeBSD System Manager's Manual
                   9        FreeBSD Kernel Developer's Manual

             ボリューム名は任意であるか、もしくは次のものを取ることができます:

                   USD      System User's Supplementary Documents
                   PS1      System Programmer's Supplementary Documents
                   AMD      System Ancestral Manual Documents
                   SMM      System Manager's Manual
                   URM      System Reference Manual
                   PRM      System Programmer's Manual
                   KM       System Kernel Manual
                   IND      System Manual Master Index
                   LOCAL    System Local Manual
                   CON      System Contributed Software Manual

             です) と中央に書かれる文字列を示しています。

                   .Dt FOO 7         `FOO(7)' `System Reference Manual'
                   .Dt FOO 2 mac68k  `FOO(2)' `System Programmer's Manual
                                     (mac68k Architecture)'
                   .Dt FOO "" bar    `FOO' `bar'

             ローカルな追加項目や OS に特化した追加項目が、ファイル mdoc.local
             にあるかもしれません。このファイル中で `volume-ds-XXX' (前者のタ
             イプについて) および `volume-as-XXX' (後者のタイプについて) とい
             う名前の文字列を検索してください。ここで `XXX' は `.Dt' マクロで
             使用されるキーワードを表しています。

             このマクロは呼び出し不可能であり、構文解析もされません。

     .Os [<オペレーティングシステム>] [<リリース番号>]
             第 1 パラメータが空の場合、デフォルト値 `FreeBSD 4.4' が使用され
             ます。これは、ローカルの設定ファイル mdoc.local で上書きできま
             す。一般的には、オペレーティングシステムの名称には一般的な頭字語
             (略称) を使わなければなりません。例えば BSD や ATT といったもので
             す。リリース番号は、各システムでの標準のリリースの命名法を使用し
             ます。次の表では、いくつか事前に定義されているオペレーティングシ
             ステムに対して取り得る第 2 引数をリストしています。 `.Dt' と同じ
             ように、ローカルな追加項目が mdoc.local に定義されているかもしれ
             ません。このファイル中で `operating-system-XXX-YYY' という名前の
             文字列を検索してください。ここで `XXX' はオペレーティングシステム
             の頭字語 (略称) そして `YYY' がリリース ID です。

                   ATT      7th, 7, III, 3, V, V.2, V.3, V.4

                   BSD      3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4

                   NetBSD   0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a,
                            1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.5

                   FreeBSD  1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5,
                            2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6,
                            2.2.7, 2.2.8, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0,
                            4.1, 4.2, 5.0

             ATT に関しては、判別できない第 2 パラメータがある時にはそれを文字
             列 UNIX に置き換えます。事前に定義されているその他の頭字語 (略称)
             については、そのようなパラメータは無視され、警告メッセージが出力
             されます。認識できない引数は、ページフッタ中に記述された通りに表
             示されます。例えば、典型的なフッタは次のようになるでしょう:

                   .Os BSD 4.3

             は `4.3 Berkeley Distribution' となります。また、ローカルで作られ
             たセットの例では、

                   .Os CS Department
                   .Dd January 25, 2001

             それ以外の場合は現在の日付が使用され、パラメータは無視されます。

             このマクロは呼び出し不可能であり、構文解析もされません。


マニュアル領域および一般テキスト領域の紹介

   B>こB>のB>名B>前B>にB>はB>何B>が...
     マニュアル領域のマクロ名はコマンドやサブルーチン、それに関連ファイルを説
     明するために使われている日常のインフォーマルな言葉から取られています。こ
     の言葉と少し違うバリエーションのものがマニュアルページを書く上での 3 つの
     異なった側面を記述するのに使われます。最初のものは、 -mdoc マクロ使用方法
     の説明です。2 番目は -mdoc マクロを 用いた UNIX コマンドの記述です。 3 番
     目はコマンドを通常の言葉の感覚でユーザに示したものです。これはすなわち、
     マニュアルページのテキスト中でのコマンドの説明となります。

     最初のケースでは、 troff(1) マクロはそれ自身、一種のコマンドとなっていま
     す。 troff コマンドは一般的に以下のような形式をとります。

           .Xx argument1 argument2 ...

     `.Xx' はマクロコマンドもしくは要求を示しており、それに続くものはすべて処
     理されるべき引数として処理されます。 2 番目のケースでは、コンテントマクロ
     を使用する UNIX コマンドの記述がもう少し含まれます。典型的な SYNOPSIS コ
     マンド行はこのように表示されます。

           filter [-flag] <infile> <outfile>

     ここで filter はコマンド名であり、角括弧で囲まれた文字列 -flag は フラグ
     引数で、これは角括弧で囲むことによってオプションであることを示していま
     す。 -mdoc の用語では、 <infile> および <outfile> は メタ引数と称されてい
     ます。この例では、ユーザは山括弧 (<>) の中で与えられたメタ引数を実際の
     ファイル名に置き換えなくてはなりません。このドキュメントでは、メタ引数は
     -mdoc コマンドを記述するのに使用していることに注意してください。多くのマ
     ニュアルページでは、メタ変数はわざわざ山括弧を使って書かれていません。上
     の例を整形したマクロは以下のものです。

           .Nm filter
           .Op Fl flag
           .Ao Ar infile Ac Ao Ar outfile Ac

     3 番目のケースでは、コマンドの説明や構文に上記の例の両方が使われ、さらに
     細かい記述が追加されるでしょう。上の例での引数 <infile> および <outfile>
     は オペランドもしくは ファイル引数として参照されます。コマンド行の引数の
     リストはかなり長くなる場合もあります。

           make  [-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I
                 directory] [-j max_jobs] [variable=value] [target ...]

     ここではコマンド make について記述しており、 makefile をフラグ -f の引数
     としています。またオプションのファイルオペランドである target についても
     言及しています。言葉での説明では、こういった詳細な記述が混乱を防いでくれ
           .Op Ar target ...
           .Ek

     マクロ `.Bk' および `.Ek' は キープセクションにおいて解説されています。

   B>一B>般B>的B>なB>構B>文
     マニュアル領域のマクロと一般テキスト領域のマクロとはいくつか小さな違いが
     あるものの、同様な構文を使用しています。とりわけ、 `.Ar', `.Fl', `.Nm',
     および `.Pa' は引数なしで呼び出された時の違いしかありません。また、 `.Fn'
     および `.Xr' は引数のリストの順番が異なります。すべてのコンテントマクロが
     句読点を認識し、それを正しく扱うには、各々の句読点文字が先行する空白で分
     離されている必要があります。次のように指定されている場合、

           .Ar sptr, ptr),

     その結果は以下のようになります。

           sptr, ptr),

     ここでは句読点は認識されず、すべての出力は `.Ar' で使用されるフォントで行
     われています。句読点が空白文字で区切られている場合、

           .Ar sptr , ptr ) ,

     結果は以下のようになります。

           sptr, ptr),

     今度は句読点が認識され、出力はデフォルトのフォントで行われ引数文字列とは
     区別されています。句読点文字の特別な意味を取り除くには、 `\&' でエスケー
     プしてください。

     troff はマクロ言語としての限界から、以下のような、数学、論理学、引用符の
     集合のメンバを含んだ文字列を表現するのは困難です。

                 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

     問題なのは、文字によって示唆されている操作もしくは評価が、実行されるべき
     であると troff が仮定する場合があることです。これらの文字が予期しない形で
     評価されないようにするには、 `\&' でこれらをエスケープしてください。最初
     のコンテントマクロは、以下の `.Ad' において、その典型的な構文が示されてい
     ます。


マニュアル領域

   B>アB>ドB>レB>ス
     アドレスマクロはアドレスの構成を識別します。

           使い方: .Ad <アドレス> ...

                    .Ad addr1           addr1
                    .Ad addr1 .         addr1.
                    .Ad addr1 , file2   addr1, file2

                    .An "Joe Author" Aq nobody@FreeBSD.org
                                            Joe Author <nobody@FreeBSD.org>

                    .An "Joe Author" ) ) ,  Joe Author)),

     デフォルトの文字幅は 12n です。

     AUTHORS セクションでは、 `.An' リクエストは改行を引き起こし、新しい名前が
     それぞれの行に表示されます。この動作が望ましくない場合、

           .An -nosplit

     を呼び出すことで無効にできます。それぞれの行に表示させる動作に戻したい場
     合は、

           .An -split

     と記述します。

   B>引B>数
     引数マクロ .Ar はコマンド行の引数を参照する際にはいつでも使用することがで
     きます。引数なしで呼ばれた場合、 `file ...' が出力になります。

           使い方: .Ar [<引数>] ...

                    .Ar              file ...
                    .Ar file1        file1
                    .Ar file1 .      file1.
                    .Ar file1 file2  file1 file2
                    .Ar f1 f2 f3 :   f1 f2 f3:
                    .Ar file ) ) ,   file)),

     デフォルト幅は 12n です。

   B>コB>ンB>フB>ィB>ギB>ュB>レB>ーB>シB>ョB>ンB>宣B>言 (B>セB>クB>シB>ョB>ン 4 B>のB>み)
     `.Cd' マクロはセクション 4 のマニュアルにおいて、デバイスインタフェースの
     config(8) による宣言の説明に使われます。

           使い方: .Cd <引数> ...

                    .Cd "device le0 at scode?"  device le0 at scode?

     SYNOPSIS セクションでは `.Cd' リクエストはその引数が表示される前後で改行
     を入れます。

     デフォルト幅は 12n です。

   B>コB>マB>ンB>ドB>修B>飾B>子
     コマンド修飾子は `.Cm' マクロがすべての引数の前にダッシュ文字を付けないこ
     とを除いて、 `.Fl' (フラグ) コマンドと同じです。伝統的にフラグはダッシュ
     文字に引き続いて指定されますが、この方法を使わないコマンドやコマンドのサ
     デフォルト幅は 12n です。

   errno
     `.Er' errno マクロは、セクション 2, 3, 9 のライブラリルーチンにおけるエラ
     ーの戻り値を指定します。下記の 2 番目の例では `.Er' は一般テキスト領域マ
     クロである `.Bq' (これはセクション 2 のマニュアルページで使われています)
     と共に使われています。

           使い方: .Er <errno のタイプ> ...

                    .Er ENOENT      ENOENT
                    .Er ENOENT ) ;  ENOENT);
                    .Bq Er ENOTDIR  [ENOTDIR]

     デフォルト幅は 17n です。

   B>環B>境B>変B>数
     `.Ev' マクロは環境変数を指定します。

           使い方: .Ev <引数> ...

                    .Ev DISPLAY        DISPLAY
                    .Ev PATH .         PATH.
                    .Ev PRINTER ) ) ,  PRINTER)),

     デフォルト幅は 15n です。

   B>フB>ラB>グ
     `.Fl' マクロはコマンド行のフラグを扱います。フラグの前にはダッシュ `-' が
     挿入されます。ダッシュがつかない対話的なコマンドのために `.Cm' (コマンド
     修飾子) マクロが用意されています。これはダッシュを付けないことを除いて同
     じ働きをします。

           使い方: .Fl <引数> ...

                    .Fl          -
                    .Fl cfv      -cfv
                    .Fl cfv .    -cfv.
                    .Cm cfv .    cfv.
                    .Fl s v t    -s -v -t
                    .Fl - ,      --,
                    .Fl xyz ) ,  -xyz),
                    .Fl |        - |

     引数なしで `.Fl' マクロを指定すると、標準入力/標準出力を意味するダッシュ
     となります。 `.Fl' マクロにダッシュを 1 つ与えると、2 つのダッシュとなる
     ことに注意して下さい。

     デフォルト幅は 12n です。

   B>関B>数B>のB>宣B>言
     `.Fd' マクロは SYNOPSIS セクションにおいて、セクション 2 または 3 の関数
     ん。

           使い方: .In <ヘッダファイル>

                    .In stdio.h  #include <stdio.h>

   B>関B>数B>のB>型
     このマクロは SYNOPSIS セクションで使うものです。マニュアルページ中の他の
     場所でも問題なく使うことができますが、セクション 2 と 3 の SYNOPSIS セク
     ションにおいてカーネルの通常の形式で関数の型を示すことがこのマクロの目的
     です (このマクロは関数名が次の行に置かれるように改行を挿入します)。

           使い方: .Ft <型> ...

                    .Ft struct stat  struct stat

   B>関B>数 (B>ラB>イB>ブB>ラB>リB>ルB>ーB>チB>ン)
     `.Fn' マクロは ANSI C の記法を規範としています。

           使い方: .Fn <関数> [<パラメータ>] ...

                    .Fn getchar              getchar()
                    .Fn strlen ) ,           strlen()),
                    .Fn align "char *ptr" ,  align(char *ptr),

     他のマクロを呼び出すと `.Fn' 呼び出しの終了を意味することに注意してくださ
     い (閉じ括弧がその箇所に挿入されます)。

     多くのパラメータをとる関数 (これは滅多にないことですが) では、 `.Fo' マク
     ロ (関数マクロの開始) と `.Fc' マクロ (関数マクロの終了) を `.Fa' (関数の
     引数) と共に使って、この制限を回避することができます。

     使用例:

           .Ft int
           .Fo res_mkquery
           .Fa "int op"
           .Fa "char *dname"
           .Fa "int class"
           .Fa "int type"
           .Fa "char *data"
           .Fa "int datalen"
           .Fa "struct rrec *newrr"
           .Fa "char *buf"
           .Fa "int buflen"
           .Fc

     生成結果:

           int res_mkquery(int op, char *dname, int class, int type,
           char *data, int datalen, struct rrec *newrr, char *buf, int buflen)


                    .Fa d_namlen ) ) ,  d_namlen)),
                    .Fa iov_len         iov_len

     デフォルト幅は 12n です。

   B>戻B>りB>値
     `.Rv' マクロは RETURN VALUES のセクションで使うテキストを生成します。

           使い方: .Rv [-std] [<関数> ...]

     例えば、 `.Rv -std atexit' は次のテキストを生成します。

            関数 atexit() は、処理が成功すると値 0 を返します。そうでない場
            合、値 -1 が返され、グローバル変数 errno が設定されてエラーを示し
            ます。

     -std オプションはセクション 2 と 3 のマニュアルページでのみ有効です。現在
     のところ、このマクロは -std フラグなしで使用しても何も起こりません。

   B>終B>了B>スB>テB>ーB>タB>ス
     `.Ex' マクロは DIAGNOSTICS のセクションで使うテキストを生成します。

           使い方: .Ex [-std] [<ユーティリティ> ...]

     例えば `.Ex -std cat' は次のテキストを生成します。

            ユーティリティ cat は、成功すると 0 で、エラーがあった場合は >0 で
            終了します。

     -std オプションはセクション 1 と 6 と 8 のマニュアルページでのみ有効で
     す。現在のところ、このマクロは -std フラグなしで使用しても何も起こりませ
     ん。

   B>対B>話B>的B>なB>コB>マB>ンB>ド
     `.Ic' マクロは対話的なコマンド、もしくは内部コマンドを指定します。

           使い方: .Ic <引数> ...

                    .Ic :wq                :wq
                    .Ic "do while {...}"   do while {...}
                    .Ic setenv , unsetenv  setenv, unsetenv

     デフォルト幅は 12n です。

   B>ラB>イB>ブB>ラB>リB>名
     `.Lb' マクロは、関数がどのライブラリに組み込まれるかを指定します。

           使い方: .Lb <引数> ...

     `.Lb' マクロに対して使用可能な引数と結果は次の通りです:

           libtermcap   Termcap Access Library (libtermcap, -ltermcap)
           libutil      System Utilities Library (libutil, -lutil)
           libz         Compression Library (libz, -lz)

     ローカルな追加項目や OS 特有の追加項目が、ファイル mdoc.local にあるかも
     しれません。 `str-Lb-XXX' という名前の文字列を検索してください。ここで
     `XXX' は `.Lb' マクロとともに使用されるキーワードを示しています。

   B>リB>テB>ラB>ル
     リテラルマクロ `.Li' は特殊文字や変数定数、その他タイプされた通りに表示す
     る必要があるものに使用することができます。

           使い方: .Li <引数> ...

                    .Li \en          \n
                    .Li M1 M2 M3 ;   M1 M2 M3;
                    .Li cntrl-D ) ,  cntrl-D),
                    .Li 1024 ...     1024 ...

     デフォルト幅は 16n です。

   B>名B>称
     `.Nm' マクロは文書のタイトルやサブジェクト名を指定するために使われます。
     このマクロは呼び出された時の第 1 引数を覚えておくという変わった特性を持っ
     ており、それは常にそのページのサブジェクト名であるべきです。引数なしで呼
     び出されると `.Nm' は作者のために最低限の仕事をするという意味で、この初期
     化された名称を出力します。注: セクション 2 または 3 のドキュメントの関数
     名は NAME セクションにおいて `.Nm' で指定され、 SYNOPSIS セクションや残り
     のセクションでは `.Fn' で指定されます。 csh(1) での `while' コマンドのキ
     ーワードのような対話的なコマンドでは `.Ic' マクロを使う必要があります。
     `.Ic' はほとんど `.Nm' と同一ですが、それが使われたときの第 1 引数を記憶
     することはできません。

           使い方: .Nm [<引数>] ...

                    .Nm groff_mdoc  groff_mdoc
                    .Nm \-mdoc      -mdoc
                    .Nm foo ) ) ,   foo)),
                    .Nm :           groff_mdoc:

     デフォルト幅は 10n です。

   B>オB>プB>シB>ョB>ン
     `.Op' マクロはコマンド行の残りのすべての引数をオプションであることを示す
     角括弧で囲み、末尾の句読点は角括弧の外に置きます。 `.Oo' マクロと `.Oc'
     マクロ (それぞれ開き角括弧と閉じ角括弧を生成します) は複数行に渡って使う
     ことができ、また閉じ括弧の正確な位置を指定するのに使うことができます。

           使い方: .Op [<オプション>] ...

                    .Op                                []
                    .Op Fl k                           [-k]

           .Oc

     出力結果:

           [[-k kilobytes] [-i interval] [-c count]]

     `.Op' マクロおよび `.Oo' マクロのデフォルト幅はそれぞれ 14n と 10n です。

   B>パB>スB>名
     `.Pa' マクロはパス名もしくはファイル名を整形します。引数なしで呼ばれた場
     合、 `~' 文字列が出力となり、これは現在のユーザのホームディレクトリを表し
     ています。

           使い方: .Pa [<パス名>] ...

                    .Pa                    ~
                    .Pa /usr/share         /usr/share
                    .Pa /tmp/fooXXXXX ) .  /tmp/fooXXXXX).

     デフォルト幅は 32n です。

   B>規B>格
     `.St' マクロは、規格の短縮名称を正式名称に置換します。

           使い方: .St <短縮名称> ...

     使用可能な ``短縮名称/正式名称'' の組は次の通りです:

     ANSI/ISO C

           -ansiC         ANSI X3.159-1989 (``ANSI C'')
           -ansiC-89      ANSI X3.159-1989 (``ANSI C'')
           -isoC          ISO/IEC 9899:1990 (``ISO C89'')
           -isoC-99       ISO/IEC 9899:1999 (``ISO C99'')

     POSIX パート 1: System API

           -iso9945-1-90   ISO/IEC 9945-1:1990 (``POSIX.1'')
           -iso9945-1-96   ISO/IEC 9945-1:1996 (``POSIX.1'')
           -p1003.1        IEEE Std 1003.1 (``POSIX.1'')
           -p1003.1-88     IEEE Std 1003.1-1988 (``POSIX.1'')
           -p1003.1-90     ISO/IEC 9945-1:1990 (``POSIX.1'')
           -p1003.1-96     ISO/IEC 9945-1:1996 (``POSIX.1'')
           -p1003.1b-93    IEEE Std 1003.1b-1993 (``POSIX.1'')
           -p1003.1c-95    IEEE Std 1003.1c-1995 (``POSIX.1'')
           -p1003.1g-2000  IEEE Std 1003.1g-2000 (``POSIX.1'')
           -p1003.1i-95    IEEE Std 1003.1i-1995 (``POSIX.1'')

     POSIX パート 2: シェルとユーティリティ

           -iso9945-2-93   ISO/IEC 9945-2:1993 (``POSIX.2'')
           -p1003.2        IEEE Std 1003.2 (``POSIX.2'')
           -xns5.2         X/Open Networking Services Issue 5.2 (``XNS5.2'')
           -xpg3           X/Open Portability Guide Issue 3 (``XPG3'')
           -xpg4           X/Open Portability Guide Issue 4 (``XPG4'')
           -xpg4.2         X/Open Portability Guide Issue 4.2 (``XPG4.2'')
           -xsh5           X/Open System Interfaces and Headers Issue 5
                           (``XSH5'')

     その他

           -ieee754        IEEE Std 754-1985
           -iso8802-3      ISO/IEC 8802-3:1989

   B>変B>数B>のB>型
     `.Vt' マクロは型を参照するときにはいつでも使用することができます。
     SYNOPSIS セクションでは改行が挿入されます (古いスタイルの変数宣言では便利
     です)。

           使い方: .Vt <型> ...

                    .Vt extern char *optarg ;  extern char *optarg;
                    .Vt FILE *                 FILE *

   B>変B>数
     一般的な変数への参照です。

           使い方: .Va <変数> ...

                    .Va count             count
                    .Va settimer ,        settimer,
                    .Va "int *prt" ) :    int *prt):
                    .Va "char s" ] ) ) ,  char s])),

     デフォルト幅は 12n です。

   B>マB>ニB>ュB>アB>ルB>ペB>ーB>ジB>のB>クB>ロB>スB>リB>フB>ァB>レB>ンB>ス
     `.Xr' マクロは最初の引数にマニュアルページの名称をとります。オプションで
     ある第 2 引数は、文字列 (マニュアルセクションを定義します) であれば括弧で
     囲われます。

           使い方: .Xr <マニュアルページの名称> [<セクション>] ...

                    .Xr mdoc        mdoc
                    .Xr mdoc ,      mdoc,
                    .Xr mdoc 7      mdoc(7)
                    .Xr xinit 1x ;  xinit(1x);

     デフォルト幅は 10n です。


一般テキスト領域

   AT&T B>マB>クB>ロ

           使い方: .At [<バージョン>] ...
                    .Bx 4.3 .   4.3BSD.
                    .Bx -devel  BSD (currently under development)

     <バージョン> が文字列 `BSD' の前につきます。 <リリース> には次の値をとる
     ことができます:

           Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2

   NetBSD B>マB>クB>ロ

           使い方: .Nx [<バージョン>] ...

                    .Nx        NetBSD
                    .Nx 1.4 .  NetBSD 1.4.

     <バージョン> にとり得る値については前述の タイトルマクロセクションの
     `.Os' リクエストの説明を参照してください。

   FreeBSD B>マB>クB>ロ

           使い方: .Fx [<バージョン>] ...

                    .Fx        FreeBSD
                    .Fx 2.2 .  FreeBSD 2.2.

     <バージョン> にとり得る値については前述の タイトルマクロセクションの
     `.Os' リクエストの説明を参照してください。

   OpenBSD B>マB>クB>ロ

           使い方: .Ox [<バージョン>] ...

                    .Ox 1.0  OpenBSD 1.0

   BSD/OS B>マB>クB>ロ

           使い方: .Bsx [<バージョン>] ...

                    .Bsx 1.0  BSD/OS 1.0

   UNIX B>マB>クB>ロ

           使い方: .Ux ...

                    .Ux  UNIX

   B>強B>調B>マB>クB>ロ
     テキストは `.Em' マクロを用いて強調することができます。通常強調に用いられ
     るフォントはイタリック体です。

           使い方: .Em <引数> ...


     <フォントモード> は次の 3 種類のうちのいずれかでなくてはなりません。

           Em | -emphasis  `.Em' マクロがテキストのブロック全体に対して使用さ
                           れた場合と同じになります。
           Li | -literal   `.Li' マクロがテキストのブロック全体に対して使用さ
                           れた場合と同じになります。
           Sy | -symbolic  `.Sy' マクロがテキストのブロック全体に対して使用さ
                           れた場合と同じになります。

     いずれのマクロも呼び出し不可能であり、構文解析もされません。

   B>囲B>い/B>クB>ォB>ーB>トB>マB>クB>ロ
     囲いの概念はクォートと似たものです。 1 つ以上の文字列が引用符や括弧のよう
     な文字のペアで囲まれているオブジェクトを指します。クォートと囲いという用
     語はこの文書を通して同じ意味で使われます。ほとんどの 1 行の囲いマクロは
     クォートであることをほのめかすために、小文字の `q' で終了しますが、例外も
     いくつかあります。各々の囲いマクロに対し、開始マクロと終了マクロのペアも
     あり、それぞれ小文字の `o' と `c' で終了します。

         クォート   開始   終了   機能                     結果
         .Aq        .Ao    .Ac    山括弧による囲い         <string>
         .Bq        .Bo    .Bc    角括弧による囲い         [string]
         .Brq       .Bro   .Brc   中括弧による囲い         {string}
         .Dq        .Do    .Dc    2 重引用符               ``string''
         .Eq        .Eo    .Ec    囲い文字列 (XX による)   XXstringXX
         .Pq        .Po    .Pc    括弧による囲い           (string)
         .Ql                      クォートされたリテラル   `string' もしくは string
         .Qq        .Qo    .Qc    まっすぐな 2 重引用符    "string"
         .Sq        .So    .Sc    1 重引用符               `string'

     `q' および `o' で終わるマクロはすべてデフォルト幅が 12n です。

     .Eo, .Ec  これらのマクロはそれぞれ第 1 引数に囲い始めに使う文字列と囲い終
               わりに使う文字列をとります。

     .Es, .En  オリジナルの troff プログラムでは、引数の数が 9 つまでという制
               限がありましたので、(Eo, Ec とは) 別の 2 つのマクロが実装されて
               います。現在は非推奨になっています。 `.Es' は第 1 引数と第 2 引
               数に左囲い文字列および右囲い文字列をとります。この文字列は、
               `.En' の引数を囲うのに使用されます。デフォルト幅は、どちらのマ
               クロも 12n です。

     .Eq       このマクロの第 1、第 2 引数はそれぞれ囲い始めに使う文字列と囲い
               終わりに使う文字列であり、この文字列の後に囲われる引数が続きま
               す。

     .Ql       クォートされたリテラルマクロは troff モードと nroff モードで
               違った挙動をします。 nroff で整形された場合、クォートされたリテ
               ラルは常にクォートされます。 troff で整形された場合、その要素の
               幅が固定幅文字 3 文字分の幅よりも小さいときのみクォートされま
               す。これにより、リテラル (固定幅) フォントへフォントを変更する

     .Ap       `.Ap' マクロはアポストロフィを追加し、特別なテキストモードから
               抜けます。そして `.No' モードで続けます。

     クォートの例:

           .Aq                      <>
           .Aq Pa ctype.h ) ,       <ctype.h>),
           .Bq                      []
           .Bq Em Greek , French .  [Greek, French].
           .Dq                      ``''
           .Dq string abc .         ``string abc''.
           .Dq '^[A-Z]'             ``'^[A-Z]'''
           .Ql man mdoc             `man mdoc'
           .Qq                      ""
           .Qq string ) ,           "string"),
           .Qq string Ns ),         "string),"
           .Sq                      `'
           .Sq string               `string'
           .Em or Ap ing            or'ing

     囲いマクロの入れ子についての良い例については、オプションマクロ `.Op' を参
     照してください。このマクロは上でリストされているような囲いマクロと同じベ
     ースの上に作られています。 `.Xo' と `.Xc' 拡張引数リストマクロについては
     後で述べます。

   B>無B>操B>作B>もB>しB>くB>はB>通B>常B>テB>キB>スB>トB>マB>クB>ロ
     `.No' マクロは、マクロコマンド行において整形されては ならないパラメータ用
     に使用できます。この英単語 (マクロでなく) をパラメータとして本当に使いた
     い場合は、この単語 `No' に `\&' を足すように注意してください。

           使い方: .No <引数> ...

                    .No test Ta with Ta tabs  test     with     tabs

     デフォルト幅は 12n です。

   B>空B>白B>なB>しB>マB>クB>ロ
     `.Ns' マクロは、現在の位置とマクロの第 1 パラメータとの間に空白を挿入する
     のを抑止します。例えば、フラグと引数の間に空白を含まない古いスタイルの引
     数リストを使う場合に便利です:

           使い方: ... <引数> Ns [<引数>] ...
                   .Ns <引数> ...

                    .Op Fl I Ns Ar directory  [-Idirectory]

     注: `.Ns' マクロは他のマクロ名が続かなければ、スペースを除去したあとに
     `.No' マクロを常に起動します。リクエストとして使用される場合 (つまり、 `
     使い方' の行での 2 番目の形式です)、 `.Ns' マクロは `.No' と同一です。

   B>セB>クB>シB>ョB>ンB>のB>クB>ロB>スB>リB>フB>ァB>レB>ンB>ス
     `.Sx' マクロは同一文書内でのセクションのヘッダへの参照を指定します。

     デフォルト幅は 6n です。

   B>数B>学B>記B>号
     数学記号やそれに似たものについては、このマクロを使用してください。

           使い方: .Ms <数学記号> ...

                    .Ms sigma  sigma

     デフォルト幅は 6n です。

   B>参B>考B>文B>献B>とB>引B>用
     次のマクロは多少なりとも参考文献を扱えるようにと意図したものです。これら
     のマクロは、せいぜい refer(1) スタイルの参考文献のサブセットを手動で作成
     しやすくする程度です。

           .Rs     参考文献の開始 (引数はとりません)。 SEE ALSO セクションでは
                   改行を挿入し、参考文献の終了マクロが読み込まれるまで参考文
                   献の情報を収集します。
           .Re     参考文献の終了 (引数はとりません)。参考文献が表示されます。
           .%A     参考文献の作者名。1 回の呼び出しにつき、作者名をひとつ指定
                   します。
           .%B     書籍のタイトル。
           .%C     市 / 場所 (まだ実装されていません)。
           .%D     日付。
           .%I     発行者/出版社名。
           .%J     定期刊行物の名称。
           .%N     発行番号。
           .%O     追加情報。
           .%P     ページ番号。
           .%Q     組織内部、あるいは外部の著者。
           .%R     報告書の名称。
           .%T     記事のタイトル。
           .%V     巻数。

     `%' で始まるマクロは呼び出し不可能ですが、通常の方法で複数の引数をとるこ
     とができます。パラメータとしては `.Tn' マクロのみ扱います。その他のマクロ
     を使うと奇妙な出力が得られてしまいます。 `.%B' および `.%T' を `.Rs/.Re'
     環境の外側では使用することができます。

     使用例:

           .Rs
           .%A "Matthew Bar"
           .%A "John Foo"
           .%T "Implementation Notes on foobar(1)"
           .%R "Technical Report ABC-DE-12-345"
           .%Q "Drofnats College, Nowhere"
           .%D "April 1991"
           .Re


     デフォルト幅は 10n です。

   B>拡B>張B>引B>数
     .Xo と .Xc マクロによって、 `.It' マクロ (後述) についてマクロ境界での引
     数リストを拡張することができます。 .Xo と .Xc マクロは囲いを開いたり閉じ
     たりする他のすべてのマクロに対して同じように実装されている (もちろん文字
     は挿入しません) ということに注意してください。つまり、次の例もこれらのマ
     クロには当てはまります。

     次は、スペーシングをオフにするために空白モードマクロを使った `.Xo' の使用
     例です。

           .Sm off
           .It Xo Sy I Ar operation
           .No \en Ar count No \en
           .Xc
           .Sm on

     これは以下のような結果になります。

           Ioperation\ncount\n

     例をもうひとつ:

           .Sm off
           .It Cm S No / Ar old_pattern Xo
           .No / Ar new_pattern
           .No / Op Cm g
           .Xc
           .Sm on

     これは以下のような結果になります。

           S/old_pattern/new_pattern/[g]

     囲いマクロを使った `.Xo' の他の例: 変数の値をテストして下さい。

           .It Xo
           .Ic .ifndef
           .Oo \&! Oc Ns Ar variable Oo
           .Ar operator variable ...
           .Oc Xc

     結果は以下の通りです。

           .ifndef [!]variable [operator variable ...]


ページ構造領域

   B>セB>クB>シB>ョB>ンB>ヘB>ッI</I>ダ
     次の `.Sh' セクションヘッダマクロは、すべてのマニュアルページで必須のもの
     です。残りのセクションヘッダはマニュアルページの作者の裁量において、推奨
                        スは小さいものですので、できるだけ簡潔で分かりやすいも
                        のでなければなりません。

                        `.Nd' は全ての引数の頭に `-', を印字します。

     .Sh LIBRARY        このセクションは、セクション 2 および 3 の関数呼び出し
                        のためにあります。このセクションには、 `.Lb' マクロ呼
                        び出し 1 つのみが含まれている必要があります。 ライブラ
                        リ名を参照してください。

     .Sh SYNOPSIS       SYNOPSIS セクションはそのマニュアルページのサブジェク
                        トとなっている項目の典型的な使用法を説明します。
                        `.Nm', `.Cd', あるいは `.Fn' です (他には `.Fo',
                        `.Fc', `.Fd', `.Ft' のマクロも必要な場合があります)。
                        関数名マクロ `.Fn' はセクション 2 と 3 のマニュアルペ
                        ージにおいて必須のもので、コマンドと一般名称マクロ
                        `.Nm' はセクション 1, 5, 6, 7, 8 で必須の項目です。セ
                        クション 4 のマニュアルでは `.Nm' か `.Fd' 、もしくは
                        設定デバイス使用法マクロ `.Cd' が必要です。その他のい
                        くつかのマクロが次に示すような書式行を生成するために必
                        要なことがあります:

                              cat [-benstuv] [-] file ...

                        次のマクロが使われています:

                              .Nm cat
                              .Op Fl benstuv
                              .Op Fl
                              .Ar

     .Sh DESCRIPTION    ほとんどの場合、 DESCRIPTION セクションでの最初のテキ
                        ストはそのコマンド、関数もしくはファイルについての短い
                        段落で、オプションの構文リストとそれぞれの説明がそれに
                        続きます。そのようなリストを作成するには `.Bl' (リスト
                        開始マクロ)、 `.It' (リスト項目マクロ)、 `.El' (リスト
                        終了マクロ) を使用します (後述の リストとカラムセク
                        ションを参照)。

     .Sh IMPLEMENTATION NOTES
                        特定の実装に関する情報はここに置く必要があります。

     .Sh RETURN VALUES  セクション 2, 3, 9 の関数の戻り値はここに来る必要があ
                        ります。 `.Rv' を使用して、セクション 2 および 3 のラ
                        イブラリ関数の RETURN VALUES セクションを生成すること
                        ができます。 戻り値の項を参照してください。

     次の `.Sh' セクションヘッダはマニュアルページの好ましいレイアウトの一部で
     あり、一貫性を保つために適切に使われなければなりません。これらは使われる
     順番にリストされています。

     .Sh ENVIRONMENT    ENVIRONMENT セクションでは関連する環境変数およびそれら
                        ションやパラメータ) をここにリストする必要があります。

     .Sh ERRORS         特定のエラーハンドリング、特にライブラリ関数 (マニュア
                        ルページのセクション 2, 3, 9) でのエラーハンドリングは
                        ここで説明する必要があります。 `.Er' マクロはエラー
                        (errno) を指定するのに使用されます。

     .Sh SEE ALSO       SEE ALSO セクションには、そのマニュアルページの題材に
                        関する資料への参照と他の関連するマニュアルページへのク
                        ロスリファレンスが記載されます。クロスリファレンスは
                        `.Xr' マクロによって指定されます。現在、 refer(1) スタ
                        イルのリファレンスには適合していません。

                        クロスリファレンスはセクション番号順、同一セクションに
                        あるものはアルファベット順に並べ、カンマで区切ることを
                        推奨します。以下に例を示します:

                        ls(1), ps(1), group(5), passwd(5)

     .Sh STANDARDS      コマンドやライブラリ関数やファイルが、 IEEE Std 1003.2
                        (``POSIX.2'') や ANSI X3.159-1989 (``ANSI C'') のよう
                        な特定の実装によるものであれば、ここで記述します。もし
                        コマンドがどの規格にも基づいていなければ、その歴史は
                        HISTORY のセクションで説明されなければなりません。

     .Sh HISTORY        特定の規格に基づいていないコマンドは、このセクションで
                        その歴史の概要を説明する必要があります。

     .Sh AUTHORS        クレジットはここに置く必要があります。人物名を指定する
                        には `.An' マクロを使用する必要があります。

     .Sh BUGS           あきらかな問題はここで記述します。

     ユーザ指定の `.Sh' セクションを追加することができます。例えば、このセク
     ションは以下のように設定されています。

                    .Sh "ページ構造領域"

   B>サB>ブB>セB>クB>シB>ョB>ンB>ヘB>ッI</I>ダ
     サブセクションヘッダはセクションヘッダとまったく同じ文法をしています。
     `.Ss' は構文解析されますが、一般的に呼び出し不可能です。このマクロは、
     `.Ss' の呼び出し時にのみ引数として使用できます。このとき、 `.Ss' のデフォ
     ルトフォントが再度有効になります。

     デフォルト幅は 8n です。

   B>段B>落B>とB>行B>スB>ペB>ーB>ス

     .Pp  `.Pp' 段落コマンドは必要な場合に行スペースを指定するために使われま
          す。このマクロは `.Sh' マクロや `.Ss' マクロの後、ならびに `.Bl' マ
          クロや `.Bd' マクロの前では必要ありません (いずれのマクロも -compact
          フラグが指定されていなければ垂直方向の距離を宣言します)。

     キープマクロについてはもっと作業をする必要があります。特に -line オプショ
     ンは追加する必要があるでしょう。

   B>例B>示B>とB>デB>ィB>スB>プB>レB>イ
     ディスプレイには 7 つのタイプがあります。

     .D1  (D-いちです) インデントされたテキストを 1 行表示します。このマクロは
          構文解析されますが、呼び出し不可能です。

                -ldghfstru

          これは次の指定で生成されたものです: .D1 Fl ldghfstru

     .Dl  (D-エルです) インデントされた リテラルテキストを 1 行表示します。
          `.Dl' マクロの例は本ファイル中にわたって使われています。これによって
          1 行のテキストのインデント (表示) が可能になります。デフォルトフォン
          トは固定幅 (リテラル) に設定されます。 `.Dl' は構文解析されますが、
          呼び出し不可能です。

                % ls -ldg /usr/local/bin

          これは、次の指定で生成されたものです: .Dl % ls -ldg /usr/local/bin

     .Bd  ディスプレイ開始。 `.Bd' ディスプレイは `.Ed' マクロで終了しなければ
          なりません。これは、次の書式をとります:

                .Bd {-literal | -filled | -unfilled | -ragged | -centered}
                     [-offset <文字列>] [-file <ファイル名>] [-compact]

          -ragged             行詰めされますが、右マージンは調整しません (左マ
                              ージンのみです)。
          -centered           現在の左マージンと右マージン間の中央線です。線そ
                              れぞれが中央揃えになるということに注意してくださ
                              い。
          -unfilled           行詰めしません。テキストのブロックを入力されたま
                              まの状態で表示します。改行もユーザが指定した通り
                              に使われます。このため、何の警告メッセージも出さ
                              ずに長過ぎる行を生成する可能性があります。
          -filled             行詰めされたブロックを表示します。テキストブロッ
                              クが整形されます (つまり、テキストは左右どちら側
                              にも揃えられます)。
          -literal            リテラルフォント (通常固定幅) でブロックを表示し
                              ます。ソースコードや、単純にタブもしくは空白で整
                              えられたテキストには便利です。
          -file <ファイル名>  -file フラグに続いた名前を持ったファイルが読み込
                              まれ、指定されたディスプレイタイプで `.Bd' と
                              `.Ed' マクロで囲まれたデータよりも前に表示されま
                              す。ファイル中の troff/-mdoc コマンドはどんなも
                              のでも処理されます。
          -offset <文字列>    -offset が以下の文字列のいずれかとともに指定され
                              ていると、その文字列は次のテキストのブロックのイ
                              ンデントのレベルを示すものとして解釈されます。
                                          分) です。
                              indent-two  デフォルトのインデント値の 2 倍分イ
                                          ンデントします。
                              right       これはブロックをページの右端から約 2
                                          インチ離して 左揃えします。このマク
                                          ロはちゃんと動作する必要があるのです
                                          が、 troff ではまったくちゃんと動作
                                          してくれていません。

                              <文字列> がそれ以外で正しい数値表現をしている場
                              合 (`u' 以外のスケール指示子を伴う)、インデント
                              用にその値を使用します。スケール指示子のなかで最
                              も役に立つものは `m' および `n' です。これらはい
                              わゆる EmEn square を指定します。これは、現
                              在のフォントでの文字 `m' および文字 `n' の幅とほ
                              ぼ同じです ( nroff の出力については、どちらのス
                              ケール指示子でも同じ値が得られます )。 <文字列>
                              が数値表現をしていない場合、文字列は -mdoc マク
                              ロ名であるかどうか検査され、このマクロに関連する
                              デフォルトのオフセット値が使われます。最終的にす
                              べてのテストが失敗した場合 the width of <文字列>
                              の幅 (固定幅フォントでのタイプセット) がオフセッ
                              トと見なされます。
          -compact            ディスプレイを開始するときに垂直方向の空白を挿入
                              しないようにします。

     .Ed  ディスプレイの終了 (引数はとりません)。

   B>リB>スB>トB>とB>カB>ラB>ム
     リスト開始マクロ `.Bl' で開始できるリストには何種類かあります。リスト中の
     項目は項目マクロ `.It' で指定され、各リストは `.El' マクロで終了しなけれ
     ばなりません。リストはリスト自身やディスプレイの中で入れ子にすることがで
     きます。リスト中でカラムを使ったり、カラムの中でリストを使ったりすること
     については検証されていません。

     さらに、タグ幅、リストのオフセット、コンパクトの度合 (項目間の空白行が許
     されているかどうか) のようなリストの属性をいくつか指定することができま
     す。本ドキュメントのほとんどはタグ (-tag) スタイルリストで整形されていま
     す。

     このマクロは次の文法規則を持っています:

           .Bl {-hang | -ohang | -tag | -diag | -inset} [-width <文字列>]
                [-offset <文字列>] [-compact]
           .Bl -column [-offset <文字列>] <文字列1> <文字列2> ...
           .Bl {-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset
                <文字列>] [-compact]

     次に、このリストタイプの詳細な解説を行います。

     -bullet  ビュレットリストです。


                    .Bl -dash -offset indent -compact
                    .It
                    1 つ目のダッシュはここにきます。
                    .It
                    2 つ目のダッシュはここにきます。
                    .El

              生成結果は次の通りです:

                    -   1 つ目のダッシュはここにきます。
                    -   2 つ目のダッシュはここにきます。

     -enum    箇条書きリストです。

                    .Bl -enum -offset indent -compact
                    .It
                    1 つ目の項目はここにきます。
                    .It
                    2 つ目の項目はここにきます。
                    .El

              生成結果は次の通りです:

                    1.   1 つ目の項目はここにきます。
                    2.   2 つ目の項目はここにきます。

              箇条書きリストを入れ子にしたい場合、 -nested フラグを使用してく
              ださい (第 2 レベルのリストが開始されます):

                    .Bl -enum -offset indent -compact
                    .It
                    1 つ目の項目はここにきます。
                    .Bl -enum -nested -compact
                    .It
                    2 つ目の項目はここにきます。
                    .It
                    3 つ目の項目はここにきます。
                    .It
                    .El
                    .It
                    4 つ目の項目はここにきます。
                    .El

              生成結果は次の通りです:

                    1.   1 つ目の項目はここにきます。
                         1.1.   2 つ目の項目はここにきます。
                         1.2.   3 つ目の項目はここにきます。
                    2.   4 つ目の項目はここにきます。

     -item    リストの印をつけない -item タイプのリストです。
                    1 つ目の項目はここにきます。 1 つ目の項目はここにきます。
                    1 つ目の項目はここにきます。

                    2 つ目の項目はここにきます。 2 つ目の項目はここにきます。
                    2 つ目の項目はここにきます。

     -tag     タグつきリストです。タグ幅を指定するには -width を使用してくださ
              い。

                    SL    プロセスが sleep している時間 (ブロックされた秒数)
                    PAGEIN
                          そのプロセスによって、まだメモリにロードされていない
                          ページへの参照が起こることにより生じたディスク I/O
                          の回数
                    UID   数値表記によるプロセス所有者のユーザ ID
                    PPID  数値表記による親プロセスの ID、プロセスの優先度 (割
                          り込み不可の待機状態のときには、正でない値になる)

              元のテキストは次の通りです:

                    .Bl -tag -width "PPID" -compact -offset indent
                    .It SL
                    プロセスが sleep している時間 (ブロックされた秒数)
                    .It PAGEIN
                    そのプロセスによって、まだメモリにロードされていないページへの参照が
                    起こることにより生じたディスク
                    .Tn I/O
                    の回数
                    .It UID
                    数値表記によるプロセス所有者のユーザ ID
                    .It PPID
                    数値表記による親プロセスの ID、プロセスの優先度
                    (割り込み不可の待機状態のときには、正でない値になる)
                    .El

     -diag    診断リストはセクション 4 の診断リストを生成するもので、呼び出し
              可能なマクロが無視されることを除き、inset リストと似ています。フ
              ラグ -width は、この文脈では意味がありません。

              使用例:

                    .Bl -diag
                    .It ここで Sy を使うことはできません。
                    このメッセージはすべて出力されます。
                    .El

              生成結果

              B>こB>こB>で Sy B>をB>使B>うB>こB>とB>はB>でB>きB>まB>せB>んB>。 このメッセージはすべて出力さ
              れます。

     -hang    ぶら下がりタグつきリストです。
                    .It Em Longer Hanged list labels
                    ラベル幅より長いぶら下がりリストのラベルは、
                    タグつき段落ラベルとは違い、段落に溶け込みます。
                    .El

     -ohang   オーバハングタグ (overhanging tags) を用いたリストは項目に対して
              インデントを使いません。タグは別の行に出力されます。

                    SL
                    プロセスが sleep している時間 (ブロックされた秒数)

                    PAGEIN
                    そのプロセスによって、まだメモリにロードされていないページ
                    への参照が起こることで生じたディスク I/O の回数

                    UID
                    数値表記によるプロセス所有者のユーザ ID

                    PPID
                    数値表記による親プロセスの ID、プロセスの優先度 (割り込み
                    不可の待機状態のときには、正でない値になる)

              元のテキストは次の通りです:

                    .Bl -ohang -offset indent
                    .It Sy SL
                    プロセスが sleep している時間 (ブロックされた秒数)
                    .It Sy PAGEIN
                    そのプロセスによって、まだメモリにロードされていないページへの参照が
                    起こることで生じたディスク
                    .Tn I/O
                    の回数
                    .It Sy UID
                    数値表記によるプロセス所有者のユーザ ID
                    .It Sy PPID
                    数値表記による親プロセスの ID、プロセスの優先度
                    (割り込み不可の待機状態のときには、正でない値になる)
                    .El

     -inset   次は、inset ラベルの例です:

                    tag タグリスト (タグ段落とも呼びます) はバークレーのマニュ
                    アルで使われている最も一般的な種類のリストです。後で述べる
                    ように、 -width 属性を使用してください。

                    diag診断リストはセクション 4 の診断リストを生成し、呼び出
                    し可能なマクロを無視するという点を除けば inset リストと似
                    ています。

                    hangぶら下がりラベルは気分の問題です。

                    ohangオーバハングラベルは空白に制限がある場合には良いで
                    属性を使用してください。
                    .It Em diag
                    診断リストはセクション 4 の診断リストを生成し、
                    呼び出し可能なマクロを無視するという点を除けば
                    inset リストと似ています。
                    .It Em hang
                    ぶら下がりラベルは気分の問題です。
                    .It Em ohang
                    オーバハングラベルは空白に制限がある場合には良いです。
                    .It Em inset
                    inset ラベルは段落ブロックを制御するのに便利で、
                    .Nm -mdoc
                    マニュアルを別のフォーマットに変換するのに有用です。
                    .El

     -column  この種類のリストは複数カラムを生成します。カラムの数および各カラ
              ムの幅は -column リストへの引数、 <string1>, <string2> 等によっ
              て決定されます。 <stringN> が `.' (ドット) で開始し直後に有効な
              -mdoc マクロ名が続く場合、 <stringN> を解釈して結果の幅を使用し
              ます。そうでない場合、 <stringN> (固定幅フォントでのタイプセッ
              ト) は N 番目の桁の幅になります。

              `.It' 引数はそれぞれ構文解析され行を生成します。行中の各列はタブ
              や `.Ta' マクロで分けられた引数です。

              次の表、

                    B>文B>字B>列    nroff    troff
                    <=        <=       <=
                    >=        >=       >=

              は次のようにして生成されています:

                    .Bl -column -offset indent ".Sy 文字列" ".Sy nroff" ".Sy troff"
                    .It Sy 文字列 Ta Sy nroff Ta Sy troff
                    .It Li <= Ta <= Ta \*(<=
                    .It Li >= Ta >= Ta \*(>=
                    .El

     その他のキーワード:

     -width <文字列>   <文字列> が `.' (ドット) で開始し直後に有効な -mdoc マ
                       クロ名が続く場合、 <文字列> を解釈し、その結果の幅を使
                       います。本ドキュメントのほとんどすべてのリストはこのオ
                       プションを使用しています。

                       使用例:

                             .Bl -tag -width ".Fl test Ao Ar 文字列 Ac"
                             .It Fl test Ao Ar 文字列 Ac
                             これは、
                             .Fl width

                       は、醜いエラーを防ぐためには引数は常に 平衡がとれていな
                       くてはなりません。例えば、本当に開き山括弧だけが必要で
                       ある場合には `.Ao Ar 文字列' と書いてはだめで、代わりに
                       `.Ao Ar 文字列 Xc' と書かなくてはなりません。

                       そうでない場合、 <文字列> が正当な数値表現である場合
                       (`u' 以外のスケール指示子を伴う)、インデント用にその値
                       を使用します。最も有用なスケール指示子は `m' と `n' で
                       す。これらはいわゆる Em および En square を指定します。
                       これは、現在のフォントでの文字 `m' および文字 `n' の幅
                       とほぼ同じです (nroff の出力については、どちらのスケー
                       ル指示子でも同じ値が得られます)。 <文字列> が数値表現を
                       していない場合、文字列は -mdoc マクロ名であるかどうか検
                       査され、このマクロに関連するデフォルトのオフセット値が
                       使われます。最終的にすべてのテストが失敗した場合 <文字
                       列> の幅 (固定幅フォントでのタイプセット) がオフセット
                       と見なされます。

                       タグリストタイプ用に幅が指定されていない場合、 `.It' が
                       起動される度に適切な幅を決定しようと試みます。 `.It' の
                       第 1 引数が呼び出し可能なマクロである場合、そのマクロの
                       デフォルト幅が使われます。そうでなければ、 `.No' のデ
                       フォルト幅が使われます。

     -offset <文字列>  <文字列> が indent である場合、デフォルトのインデント値
                       (通常 6n に設定されており、 `.Dl' または `.Bd' で使われ
                       る値と似ています) が使われます。 <文字列> が正当な数値
                       表現である場合 (`u' 以外のスケール指示子を伴う )、その
                       値をインデントに使用します。最も有用なスケール指示子は
                       `m' と `n' であり、これらはいわゆる Em および En square
                       です。これは、それぞれ現在のフォントでの `m' と `n' の
                       幅とほぼ同じです (nroff の出力については、どちらのスケ
                       ール指示子も同じ値をとります)。 <文字列> が数値表現でな
                       い場合、その文字列が -mdoc のマクロ名であるかどうか検査
                       され、このマクロに関連するデフォルトのオフセット値が使
                       われます。最終的にすべてのテストが失敗した場合、 <文字
                       列> の幅 (固定幅フォントでのタイプセット) がオフセット
                       としてとられます。

     -compact          リストの前およびリスト項目間に垂直方向の空白を挿入しな
                       いようにします。


その他のマクロ

     ここには、いままでのセクションにはうまく当てはまらなかった残りのマクロの
     リストがあります。次のマクロに対しては本物の使用例を見つけられませんでし
     た。それは `.Me' と `.Ot' です。この 2 つについても完璧を期するためにここ
     に文書化はしています。もしこの 2 つのマクロの適切な使い方をご存知であれば
     bug-groff@gnu.org までメールを送ってください (例つきで)。

     .Bt  は

                is currently in beta test.

     .Hf  (ヘッダ) ファイルをそのまま含めるにはこのマクロを使ってください。こ
          のマクロは、最初に `File:' とファイル名を表示し、その後で <ファイル>
          の内容を表示します。

                使い方: .Hf <ファイル>

          このマクロは呼び出し不可能であり、構文解析もされません。

     .Lk  将来書かれる予定です。

     .Me  正確な使用方法は分かりません。 -mdoc ソースファイル中の記述では ``メ
          ニューエントリ'' となっています。

          デフォルト幅は 6n です。

     .Mt  将来書かれる予定です。

     .Ot  正確な使用方法は分かりません。 -mdoc ソースファイル中の記述では ``古
          い関数タイプ (fortran)'' となっています。

     .Sm  空白モードを有効に (トグル) します。

                使い方: .Sm [on | off] ...

          空白モードが off の場合、マクロ引数の間に空白は挿入されません。引数
          なしで呼ばれた場合 (あるいは次の引数が `on' でも `off' でもない場合)
          `.Sm' マクロは空白モードに入ります。

     .Ud  マクロは

                currently under development.

          を表示します。

          このマクロは呼び出し不可能であり、構文解析もされません。また引数もと
          りません。


定義済み文字列

     次の文字列が定義済みです:

           B>文B>字B>列    nroff       troff     B>意B>味
           <=        <=          <=        以下
           >=        >=          >=        以上
           Rq        ''          ''        右側のダブルクォート
           Lq        ``          ``        左側のダブルクォート
           ua        ^           ^         上向き矢印
           aa        '           '         アキュートアクセント
           ga        `           `         グレーブアクセント
           q         "           "         まっすぐなダブルクォート
           Pi        pi          pi        ギリシャ語のパイ
           Ne        !=          !=        不等号
           Le        <=          <=        以下

     文字を 2 つ含んだ文字列名は `\*(xx' として表記できます。文字を 1 文字だけ
     含んだ文字列名は `\*x' と表記できます。どのような長さの文字列名に対して
     も、一般的な文法は `\*[xxx]' となります ( これは GNU troff(1) 拡張です)。


診断

     以前のバージョンの -mdoc パッケージでは利用可能だったデバッグ用マクロ
     `.Db' は取り除かれました。なぜなら、 GNU troff(1) ではパラメータをチェッ
     クするのにもっと良いファシリティを提供しているからです。さらに、このマク
     ロパッケージにはエラーや警告メッセージが多数追加されており、よりロバスト
     で饒舌なものになっています。

     唯一残ったデバッグ用マクロは `.Rd' であり、これはすべてのグローバルレジス
     タならびに文字列のレジスタダンプを出力するものです。通常のユーザが使う必
     要は決してないでしょう。


GROFF, TROFF, および NROFF を使用した整形

     デフォルトでは、このパッケージでは `latin1' や `unicode' のような TTY デ
     バイスで表示する場合には改ページやヘッダ、フッタは禁止されており、マニュ
     アルをオンラインで効率良く見ることができるようになっています。この振る舞
     いは、 groff を呼んでいるときにレジスタに 0 を指定することで変更すること
     ができます (例えば、 TTY 出力のハードコピーを作成したいときなど)。

           groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt

     両面印刷用には、レジスタ `D' を 1 に設定してください:

           groff -Tps -rD1 -mdoc foo.man > foo.ps

     ドキュメントのフォントサイズを 11pt や 12pt に変更したい場合は、レジスタ
     `S' をそれに合わせて設定してください:

           groff -Tdvi -rS11 -mdoc foo.man > foo.dvi

     レジスタ `S' は TTY デバイスに対しては無視されます。


関連ファイル

     doc.tmac          主なマニュアル用マクロパッケージです。
     mdoc.tmac         doc.tmac を呼ぶラッパファイルです。
     mdoc/doc-common   共通する文字列、定義、および印刷出力に関連する項目で
                       す。
     mdoc/doc-nroff    TTY 出力デバイス用に使用される定義です。
     mdoc/doc-ditroff  その他すべてのデバイス用に使用される定義です。
     mdoc.local        ローカルマシンでの追加項目およびカスタマイズ項目です。
     andoc.tmac        このファイルは -mdoc パッケージと -man パッケージのどち
                       らを使用すべきかをチェックします。


関連項目

     groff(1), man(1), troff(1), groff_man(7)


バグ

     セクション 3f はヘッダルーチンには追加されていません。


ABELNET VPSサービス