.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)mdoc.7	8.2 (Berkeley) 12/30/93
.\" %FreeBSD: src/share/man/man7/mdoc.7,v 1.8.2.4 1999/09/14 16:35:16 phantom Exp %
.\"
.\" jpman %Id: mdoc.7,v 1.5 1999/01/21 18:02:11 kuma Stab %
.\"
.\" WORD: display	ディスプレイ (表示よりも展示に意味が近いと思います)
.\" WORD: enclose	囲む、囲み
.\" WORD: quote		クォート
.\" WORD: open (quote)	開き…
.\" WORD: close (quote)	閉じ…
.\" WORD: content macro	コンテントマクロ
.\" WORD: parse	解析する
.Dd December 30, 1993
.Os
.Dt MDOC 7
.Sh 名称
.Nm mdoc
.Nd マクロパッケージ
.Nm \-mdoc
のクイックリファレンスガイド
.Sh 書式
.Nm groff
.Fl m Ns Ar doc
.Ar files ...
.Sh 解説
.Nm \-mdoc
パッケージは、
.Bx
マニュアルページをフォーマットするのに
使うコンテントベースおよび領域ベースのマクロのセットです。
マクロ名とその意味はクイックリファレンスとして以下に一覧が
あります。パッケージを使う上での詳細な説明は、サンプルチュートリアルの
.Xr mdoc.samples 7
を見て下さい。
.Pp
マクロは 2 つのグループに分けて述べられています。1 つ目は
構造的なページレイアウトマクロと物理的な
ページレイアウトマクロです。
2 つ目は、
マニュアル領域マクロと
一般テキスト領域マクロであり、
.Nm -\mdoc
パッケージを他の
.Xr troff
フォーマットパッケージとは異なるものとしています。
.Sh ページ構造領域
.Ss タイトルマクロ
正しいマニュアルを生成するために、以下の 3 つのマクロがこの順序で
必要になります:
.Bl -tag -width "xxxx.Os OPERATINGxSYSTEM [version/release]" -compact
.It Li "\&.Dd  " Ar "Month day, year"
ドキュメントの日付
.It Li "\&.Dt  " Ar "DOCUMENT_TITLE [section] [volume]"
大文字で記述したタイトル
.It Li "\&.Os  " Ar "OPERATING_SYSTEM [version/release]"
オペレーティングシステム
.Pq Tn BSD
.El
.Ss ページレイアウトマクロ
セクションヘッダ、段落の区切り、リスト、ディスプレイです。
.Bl -tag -width flag -compact
.It Li \&.Sh
セクションヘッダ。
正しいヘッダを、登場する順に示します:
.Bl -tag -width "IMPLEMENTATION NOTES" -compact
.It Ar NAME
名称セクション。
.Ql \&.Nm
もしくは
.Ql \&.Fn
と、
.Ql \&.Nd
マクロを含む必要があります。
.It Ar SYNOPSIS
使用方法。
.It Ar DESCRIPTION
一般的な解説。オプションとパラメータを含む必要があります。
.It Ar IMPLEMENTATION NOTES
実装に固有の情報。
.It Ar RETURN VALUES
セクション 2, 3 の関数呼び出しが使用します。
.It Ar ENVIRONMENT
環境変数を記述します。
.It Ar FILES
その題材に関係があるファイル群。
.It Ar EXAMPLES
例と助言。
.It Ar DIAGNOSTICS
普通、セクション 4 のデバイスインタフェースの診断のために使用します。
.It Ar ERRORS
セクション 2, 3 で、エラーとシグナルを取り扱います。
.It Ar SEE ALSO
クロスリファレンスと引用。
.It Ar STANDARDS
適用できるなら、規格準拠を示します。
.It Ar HISTORY
規格が適用できない場合、題材の歴史が必要です。
.It Ar BUGS
思い違い (gotcha) と警告。
.It Ar AUTHORS
必要であれば、クレジットをここに書きます。
.It Ar その他
著者の裁量によりカスタマイズしたヘッダを加えてもかまいません。
.El
.It Li \&.Ss
サブセクションヘッダ。
.It Li \&.Pp
段落区切り。
垂直な空白 (1 行) です。
.It Li \&.D1
(D-one) 1 個分のディスプレイ。
インデントして、1 テキスト行をディスプレイします。
.It Li \&.Dl
(D-ell) 1 個分のリテラルディスプレイ。
インデントして、リテラルテキストを 1 行でディスプレイします。
.It Li \&.Bd
ディスプレイブロックを開始します。
表示オプション:
.Bl -tag -width "xoffset string " -compact
.It Fl ragged
揃えない(行末はちぎれた状態)。
.It Fl filled
揃える。
.It Fl literal
リテラルテキストやコード。
.It Fl file Ar name
.Ar file
を読み込み、ディスプレイします。
.It Fl offset Ar string
オフセットディスプレイ。使用可能な
.Ar string
値:
.Bl -tag -width indent-two -compact
.It Ar left
ブロックの左寄せ (デフォルト)。
.It Ar center
センタリングするように余白を取ります。
.It Ar indent
6 つの一定幅の空白 (タブ 1 個)。
.It Ar indent-two
タブ 2 個。
.It Ar right
右から 2 インチのところにブロックを左寄せします。
.It Ar xx Ns Cm n
.Ar xx
には、
.No \&4 Ns Cm n
から
.No \&9\&9 Ns Cm n
までの数字。
.It Ar Aa
.Ar Aa
は、呼び出し可能なマクロ名。
.It Ar string
.Ar string
の幅が使われます。
.El
.El
.It Li \&.Ed
ディスプレイの終り (\&.Bd に対応)。
.It Li \&.Bl
リストの開始。リストまたは列を作成します。
オプション:
.Bl -tag -width flag -compact
.It Ar リストの型
.Bl -column xbullet -compact
.It Fl bullet Ta "丸印付きの項目リスト"
.It Fl item Ta "ラベル無しのリスト"
.It Fl enum Ta "番号付けしたリスト"
.It Fl tag Ta "タグラベルのリスト"
.It Fl diag Ta "診断リスト"
.It Fl hang Ta "ぶら下がりラベルのリスト"
.It Fl ohang Ta "突き出したラベルのリスト"
.It Fl inset Ta "挿入または追い込みラベルのリスト"
.El
.It リストのパラメータ
.Bl -tag -width "xcompact " -compact
.It Fl offset
(すべてのリスト)
上記の
.Ql \&.Bd
ディスプレイ開始を参照。
.It Fl width
.Pf ( Fl tag
と
.Fl hang
リストのみ)
.Ql \&.Bd
を参照。
.It Fl compact
(すべてのリスト)
空行を作らない。
.El
.El
.It Li \&.El
リストの終り。
.It Li \&.It
リストの項目。
.El
.Sh マニュアル領域と一般テキスト領域のマクロ
マニュアル領域マクロと一般テキスト領域マクロは、
そのほとんどが呼び出し可能なマクロに解析されるという点で特別です。例えば:
.Bl -tag -width ".Op Fl s Ar filex" -offset indent
.It Li "\&.Op Fl s Ar file"
は
.Op Fl s Ar file
を生成します。
.El
.Pp
この例では、オプション囲みマクロ
.Ql \&.Op
が解析されると、引数
.Ql s
を操作する
呼び出し可能なコンテントマクロ
.Ql \&Fl
を呼び出してから、引数
.Ql file
を操作する
呼び出し可能なコンテントマクロ
.Ql \&Ar
を呼びます。
呼び出し可能ではあるものの解析はされないマクロがありますし、
その逆もあります。
これらのマクロを、後述の
.Em 解析対象 (parsed)
と
.Em 呼出可 (callable)
の列に示します。
.Pp
言及していなければ、マニュアル領域マクロは、次の共通の構文をとります:
.Pp
.Dl \&.Va argument [\ .\ ,\ ;\ :\ (\ )\ [\ ]\ argument \...\ ]
.Pp
.Sy 注意 :
開く句読点文字と閉じる句読点文字
(訳注: 句読点文字には括弧なども含みます)
がそのように認識されるのは、
ひとつずつ登場する場合だけです。
文字列
.Ql "),"
は、句読点とは認識されず、
先行する空白文字とともに呼び出しマクロが使用しているフォントで出力されます。
引数リスト
.Ql "] ) ,"
は 3 つの連続した閉じる句読点と認識され、
文字間および (存在する場合には) 先行する引数との間には、
先行する空白文字は出力されません。
句読点文字の特別の意味は、文字列
.Ql \e&
によりエスケープされます。
例えば、次の文字列
.Bl -tag -width "&.Ar file1\ , file2\ , file3\ )\ ." -offset indent
.It Li "\&.Ar file1\ , file2\ , file3\ )\ ."
は
.Ar file1 , file2 , file3 ) .
を生成します。
.El
.ne 1i
.Ss マニュアル領域のマクロ
.Bl -column "名称" "解析対象" "呼出可" -compact
.It Em 名称	解析対象	呼出可	解説
.It Li \&Ad Ta Yes Ta Yes Ta "アドレス (このマクロは使用しないように言われています)。"
.It Li \&An Ta Yes Ta Yes Ta "著者名。"
.It Li \&Ar Ta Yes Ta Yes Ta "コマンドラインの引数。"
.It Li \&Cd Ta \&No Ta \&No Ta "コンフィギュレーション宣言 (セクション 4 のみ)。"
.It Li \&Cm Ta Yes Ta Yes Ta "コマンドライン引数修飾子。"
.It Li \&Dv Ta Yes Ta Yes Ta "定義された変数 (ソースコード)。"
.It Li \&Er Ta Yes Ta Yes Ta "エラー番号 (ソースコード)。"
.It Li \&Ev Ta Yes Ta Yes Ta "環境変数。"
.It Li \&Fa Ta Yes Ta Yes Ta "関数の引数。"
.It Li \&Fd Ta Yes Ta Yes Ta "関数の定義。"
.It Li \&Fn Ta Yes Ta Yes Ta "関数呼び出し (.Fo や .Fc も同様)。"
.It Li \&Ic Ta Yes Ta Yes Ta "対話的なコマンド。"
.It Li \&Li Ta Yes Ta Yes Ta "リテラルテキスト。"
.It Li \&Nm Ta Yes Ta Yes Ta "コマンド名。"
.It Li \&Op Ta Yes Ta Yes Ta "オプション (.Oo や .Oc も同様)。"
.It Li \&Ot Ta Yes Ta Yes Ta "古いスタイルの関数型 (Fortran のみ)。"
.It Li \&Pa Ta Yes Ta Yes Ta "パス名やファイル名。"
.It Li \&St Ta Yes Ta Yes Ta "規格 (-p1003.2 や -p1003.1 や -ansiC)。"
.It Li \&Ta Ta Yes Ta Yes Ta "次のタブコラムへのタブ揃え。"
.It Li \&Va Ta Yes Ta Yes Ta "変数名。"
.It Li \&Vt Ta Yes Ta Yes Ta "変数の型 (Fortran のみ)。"
.It Li \&Xr Ta Yes Ta Yes Ta "マニュアルのクロスリファレンス。"
.El
.Ss 一般テキスト領域のマクロ
.Bl -column "名称" "解析対象" "呼出可" -compact
.It Em "名称	解析対象	呼出可	解説"
.It Li \&%A Ta Yes Ta \&No Ta "参照の著者。"
.It Li \&%B Ta Yes Ta Yes Ta "参照の図書タイトル。"
.It Li \&%\&C Ta \&No Ta \&No Ta "参照の発行場所(市)。"
.It Li \&%\&D Ta \&No Ta \&No Ta "参照の日付。"
.It Li \&%J Ta Yes Ta Yes Ta "参照の雑誌タイトル。"
.It Li \&%N Ta \&No Ta \&No Ta "参照の刊行番号。"
.It Li \&%\&O Ta \&No Ta \&No Ta "参照の追加的な情報。"
.It Li \&%P Ta \&No Ta \&No Ta "参照のページ番号。"
.It Li \&%R Ta \&No Ta \&No Ta "参照のレポート名。"
.It Li \&%T Ta Yes Ta Yes Ta "参照の記事タイトル。"
.It Li \&%V Ta \&No Ta \&No Ta "参照の巻名。"
.It Li \&Ac Ta Yes Ta Yes Ta "カギ括弧(angle)閉じクォート。"
.It Li \&Ao Ta Yes Ta Yes Ta "カギ括弧(angle)開きクォート。"
.It Li \&Ap Ta Yes Ta Yes Ta "アポストロフィ。"
.It Li \&Aq Ta Yes Ta Yes Ta "カギ括弧(angle)クォート。"
.It Li \&At Ta \&No Ta \&No Ta Tn "AT&T UNIX。"
.It Li \&Bc Ta Yes Ta Yes Ta "角括弧(bracket)閉じクォート。"
.It Li \&Bf Ta \&No Ta \&No Ta "フォントモード始点。"
.It Li \&Bo Ta Yes Ta Yes Ta "角括弧(bracket)開きクォート。"
.It Li \&Bq Ta Yes Ta Yes Ta "角括弧(bracket)クォート。"
.It Li \&Bx Ta Yes Ta Yes Ta "BSD UNIX。"
.It Li \&Db Ta \&No Ta \&No Ta "デバッグ (デフォルトは \\*qoff\\*q)。"
.It Li \&Dc Ta Yes Ta Yes Ta "ダブル(double)閉じクォート。"
.It Li \&Do Ta Yes Ta Yes Ta "ダブル(double)開きクオート。"
.It Li \&Dq Ta Yes Ta Yes Ta "ダブル(double)クォート。"
.It Li \&Ec Ta Yes Ta Yes Ta "文字列で囲む閉じクォート。"
.It Li \&Ef Ta \&No Ta \&No Ta "フォントモード終了。"
.It Li \&Em Ta Yes Ta Yes Ta "強調 (古風な英語)。"
.It Li \&Eo Ta Yes Ta Yes Ta "文字列で囲む開きクォート。"
.It Li \&Fx Ta \&No Ta \&No Ta Tn "FreeBSD オペレーティングシステム。"
.It Li \&No Ta Yes Ta Yes Ta "通常のテキスト (no-op)。"
.It Li \&Ns Ta Yes Ta Yes Ta "空白なし。"
.It Li \&Nx Ta \&No Ta \&No Ta Tn "NetBSD オペレーティングシステム。"
.It Li \&Pc Ta Yes Ta Yes Ta "丸括弧(parenthesis)閉じクォート。"
.It Li \&Pf Ta Yes Ta \&No Ta "接頭文字列。"
.It Li \&Po Ta Yes Ta Yes Ta "丸括弧(parenthesis)開きクォート。"
.It Li \&Pq Ta Yes Ta Yes Ta "丸括弧クォート。"
.It Li \&Qc Ta Yes Ta Yes Ta "まっすぐなダブル(double)閉じクォート。"
.It Li \&Ql Ta Yes Ta Yes Ta "クォートされたリテラル。"
.It Li \&Qo Ta Yes Ta Yes Ta "まっすぐなダブル(double)開きクォート。"
.It Li \&Ox Ta \&No Ta \&No Ta Tn "OpenBSD オペレーティングシステム。"
.It Li \&Qq Ta Yes Ta Yes Ta "まっすぐなダブル(double)クォート。"
.It Li \&Re Ta \&No Ta \&No Ta "参照終了。"
.It Li \&Rs Ta \&No Ta \&No Ta "参照開始。"
.It Li \&Rv Ta \&No Ta \&No Ta "戻り値 (セクション 2 と 3 のみ)。"
.It Li \&Sc Ta Yes Ta Yes Ta "(single)閉じクォート。"
.It Li \&So Ta Yes Ta Yes Ta "(single)開きクォート。"
.It Li \&Sq Ta Yes Ta Yes Ta "(single)クォート。"
.It Li \&Sm Ta \&No Ta \&No Ta "空白モード(デフォルトは \\*qon\\*q)。"
.It Li \&Sx Ta Yes Ta Yes Ta "セクションクロスリファレンス。"
.It Li \&Sy Ta Yes Ta Yes Ta "シンボリック (古風な英語)。"
.It Li \&Tn Ta Yes Ta Yes Ta "商標またはタイプ名 (小さい大文字)。"
.It Li \&Ux Ta Yes Ta Yes Ta "UNIX。"
.It Li \&Xc Ta Yes Ta Yes Ta "拡張引数リスト終了。"
.It Li \&Xo Ta Yes Ta Yes Ta "拡張引数リスト開始。"
.El
.\" .It Sy \&Hf Ta \&No Ta \&No Ta "Include file with header"
.Pp
.Ql q
で終わるマクロ名は、引数リストの残りの項目をクォートします。
.Ql o
で終わるマクロ名はクォートの開始であり、複数行の入力に渡ります。
.Ql c
で終わる対応するマクロ名は、このクォートを閉じます。
囲みマクロは入れ子になっても良く、引数は 8 個に制限されます。
.Pp
注意: 拡張引数リストマクロ
.Pf ( Ql \&.Xo ,
.Ql \&.Xc )
と関数囲みマクロ
.Pf ( Ql \&.Fo ,
.Ql \&.Fc )
は、変則です。
拡張リストマクロは、マクロ引数が
.Xr troff
の制限である 9 個を越える場合に使われます。
.Sh コンフィギュレーション
マクロパッケージのサイト依存コンフィギュレーションのために、
ファイル
.Pa /usr/src/share/tmac/README
を参照して下さい。
.Sh 関連ファイル
.Bl -tag -width "tmac.doc-ditroff" -compact
.It Pa tmac.doc
マニュアル領域と一般テキスト領域のマクロ。
.It Pa tmac.doc-common
共通構造マクロと定義。
.It Pa tmac.doc-nroff
サイト依存の
.Xr nroff
スタイルファイル。
.It Pa tmac.doc-ditroff
サイト依存の
.Xr troff
スタイルファイル。
.It Pa tmac.doc-syms
(標準マクロのような) 特殊定義。
.El
.Sh 関連項目
.Xr mdoc.samples 7
.\"ZZZ: 3.0-RELEASE compliant by N. Kumagai 99-1.21