MDOC(7)

名前
mdoc - Macro Package -mdoc のクイックリファレンスガイド

書式
groff -mdoc files ...

説明
-mdoc パッケージは BSD man ページに用いられる内容ベース・ドメインベースのマクロである。 以下ではクイックリファレンスとしてマクロの名前とその意味をリストする。 このパッケージの利用法に関する詳細な説明は、 チュートリアル用の見本である mdoc.samples(7) を参照すること。

これは Linux の文書で通常用いられているマクロパッケージとは異なる。 しかし広く用いられているいくつかのプログラムの文書で、 このマクロが利用されている。 man(7) を見よ。

マクロは 2 つのグループに分けて説明する。 最初のグループは構造や物理的なページレイアウトに関するマクロである。 2 つめはマニュアルドメインマクロ (manual domain macro) や一般テキストドメインマクロ (general text domain macro) で、 -mdoc パッケージを他の troff フォーマットパッケージと差別化しているものである。

ページ構造のドメイン

  タイトルマクロ
正しいマニュアルページを生成するためには、これらの 3 つのマクロを この順番で書く必要がある。
.Dd   Month day, year
    文書の日付。
.Dt   DOCUMENT_TITLE [section] [volume]
    タイトルを大文字で。
.Os   OPERATING_SYSTEM [version/release]
    オペレーティングシステム (BSD).

  ページレイアウトマクロ
セクションヘッダ、段落の終わり、リスト、表示など。
.Sh セクションのヘッダ。 正しいヘッダは、現れる順に:
    NAME
        名前のセクション。 ‘.Nm’ , ‘.Fn’ , ‘.Nd’ などのマクロを含む。
    SYNOPSIS
        利用法。
    DESCRIPTION
        一般的な説明。オプションやパラメータの説明も含む。
    RETURN VALUE
        セクション 2 や 3 の関数コール。
    ENVIRONMENT
        環境変数を説明する。
    FILES
        内容に関係するファイル。
    EXAMPLES
        例やおすすめ。
    DIAGNOSTICS
        通常セクション 4 のデバイスインターフェースの診断用。
    ERRORS
        セクション 2 や 3 のエラーやシグナル処理。
    SEE ALSO
        相互参照や引用。
    CONFORMING TO
        可能なら標準への準拠。
    HISTORY
        標準が適用されていない場合は、 歴史的な内容を与えるべきである。
    BUGS
        瑕疵や警告。
    other
        筆者の判断でヘッダをあつらえてもよい。
.Ss サブセクションのヘッダ。
.Pp 段落の区切り。 垂直スペース (一行)。
.D1 (D-one) Display-one インデントしてテキストを一行表示。
.Dl (D-ell) Displey-one literal。 インデントしてリテラルなテキストを一行表示。
.Bd 表示ブロックの開始。 表示オプション:
    -ragged
        揃えない (両端は不揃い)。
    -filled
        揃える。
    -literal
        リテラルなテキストまたはコード。
    -file name
        指定された file を読んで表示する。
    -offset string
        オフセット表示。 受付ける string の値は:
        left
            ブロックを左に揃える (デフォルト)。
        center
            大まかなセンターマージン。
        indent
            定数幅の空白 6 つ (タブ 1 つ)。
        indent-two
            タブ 2 つ。
        right
            揃えブロックを右から 2 インチの位置に残す。
        xxn xx は 4n から 99n までの数字。
        Aa  Aa は呼びだし可能なマクロの名前。
        string
            string の幅が用いられる。
.Ed 表示終了 (.Bd にマッチする)。
.Bl リスト開始。 リストまたはコラムを生成する。オプションは以下:
    リスト形式
        -bullet | 中黒のアイテムリスト
        -item | ラベルなしリスト
        -enum | 数値付きリスト
        -tag | タグラベル付きリスト
        -diag | 診断リスト (diagnostic list)
        -hang | ぶらさがりラベルリスト
        -ohang | 飛び出しラベルリスト
        -inset | ラベル付きリストの挿入・継続
    リストパラメータ
        -offset
            (全てのリスト) 上記の ‘.Bd’ ディスプレイ開始 (begin-display) を見よ。
        -width
            (-tag および -hang リストのみ) ‘.Bd’. を見よ。
        -compact
            (全てのリスト) 空行を抑制する。
.El リストの終わり。
.It リスト項目。

マニュアルドメインマクロと一般テキストドメインマクロ
マニュアルドメインマクロと一般テキストドメインマクロとが 他と異なっているのは、 呼びだし可能マクロ (callable macro) の内部では、 そのほとんどがパーズされるという点である。 例えば以下のように変換される:

.Op Fl s Ar file
    → [-s file]

この例では、囲みマクロ ‘.Op’ に与えられたオプションがパーズされ、 中身の呼びだし可能なマクロである ‘-’ が呼ばれ、引数である ‘s’ に対して作用する。そして次に中身の呼びだし可能なマクロ ‘file ...’ が呼ばれ、引数である ‘file’ に作用する。呼びだし可能であるがパースされないマクロや、 その逆のマクロも存在する。このようなマクロは以下の parsed カラムや callable カラムで示す。

特に記述がなければ、マニュアルドメインマクロは共通の書式をとる:

    .Va argument [ . , ; : ( ) [ ] argument ... ]

注意: 句読文字 (punctuation character) の開き・閉じは、 それらが一度に単一の文字で現れた場合のみそのように解釈される。 文字列 ‘),’ は、句読区切りとはみなされず、その前に空白文字があれば その文字とともに、また呼び出したマクロが用いるフォントで出力される。 引数リスト ‘] ) ,’ は 3 つの連続した閉じ句読文字と解釈され、 それぞれの前にある空白文字は、各文字や (もしあれば) その前にある 引数との間には出力されない。 特殊な意味を持つ句読文字は、文字列 ‘\&’ によってエスケープできる。 例えば以下の左の文字列は右のように変換される。

.Ar file1 , file2 , file3 ) .
    → file1, file2, file3).

  マニュアルドメインマクロ
名前 | Parsed | Callable | 説明
 | Yes | Yes | アドレス (このマクロは使わない方が良い)
 | Yes | Yes | 著者の名前
file ... | Yes | Yes | コマンドライン引数
 | | | 設定の宣言 (セクション 4 のみ)
 | Yes | Yes | コマンドライン引数の修正子
 | Yes | Yes | 定義済み変数 (ソースコード)
 | Yes | Yes | エラー番号 (ソースコード)
 | Yes | Yes | 環境変数
 | Yes | Yes | 関数の引き数
Fd | Yes | Yes | 関数の宣言
 | Yes | Yes | 関数呼びだし (.Fo と .Fc も)
 | Yes | Yes | インタラクティブなコマンド
 | Yes | Yes | リテラルなテキスト
mdoc | Yes | Yes | コマンドの名前
[| Yes | Yes | オプション (.Oo と .Oc も)]
 | Yes | Yes | 古い形式の関数型 (Fortran のみ).
~ | Yes | Yes | パス名またはファイル名
 | Yes | Yes | 標準 (-p1003.2, -p1003.1, -ansiC のどれか)
 | Yes | Yes | 変数の名前
 | Yes | Yes | 変数の型 (Fortran のみ)
 | Yes | Yes | マニュアルページの相互参照

  一般テキストドメインマクロ
名前 | Parsed | Callable | 説明
%A | Yes | | 参考文献の著者
%B | Yes | Yes | 参考文献の書籍タイトル
%C | | | 参考文献の出版地 (街)
%D | | | 参考文献の日付
%J | Yes | Yes | 参考文献の雑誌名
%N | | | 参考文献の号数
%O | | | 参考文献の補助情報
%P | | | 参考文献のページ
%R | | | 参考文献のリポート名
%T | Yes | Yes | 参考文献の記事タイトル
%V | | | 参考文献の巻数
> | Yes | Yes | アングルクォートの閉じ
<| Yes | Yes | アングルクォートの開き
'| Yes | Yes | アポストロフィ
<| Yes | Yes | アングルクォート>
AT&T UNIX | | | AT&T UNIX
] | Yes | Yes | ブラケットクォートの閉じ
Bf | | | フォントモードの開始
[| Yes | Yes | ブラケットクォートの開き
[| Yes | Yes | ブラケットクォート]
BSD | Yes | Yes | BSD.
Db | | | デバッグ (デフォルトは off)
” | Yes | Yes | ダブルクォートの閉じ
“| Yes | Yes | ダブルクォートの開き
“| Yes | Yes | ダブルクォート”
 | Yes | Yes | エンクローズ文字列引用の閉じ
Ef | | | フォントモードの終了
 | Yes | Yes | 強調 (traditional English).
 | Yes | Yes | エンクローズ文字列引用の開き
FreeBSD | | | FreeBSD operating system
 | Yes | Yes | 通常のテキスト (効果なし)
 | Yes | Yes | スペース無し
) | Yes | Yes | 括弧クォートの閉じ
 | Yes | | 前置文字
(| Yes | Yes | 括弧クォートの開き
(| Yes | Yes | 括弧クォート)
" | Yes | Yes | ダブルストレートクォートの閉じ
‘| Yes | Yes | クォートされたリテラル’
"| Yes | Yes | ダブルストレートクォートの閉じ
"| Yes | Yes | ダブルストレートクォートの閉じ"
Re | | | 参考文献の終了
Rs | | | 参考文献の開始
Rv | | | 返り値 (セクション 2, 3 のみ)
’ | Yes | Yes | シングルクォートの閉じ
‘| Yes | Yes | シングルクォートの開き
‘| Yes | Yes | シングルクォート’
Sm | | | スペースモード (デフォルトは on)
 | Yes | Yes | セクションの相互参照
 | Yes | Yes | シンボリック (traditional English).
 | Yes | Yes | Trade または型名 (small Caps).
UNIX | Yes | Yes | UNIX
 | Yes | Yes | 拡張引数リストの閉じ
 | Yes | Yes | 拡張引数リストの開き

‘q’ で終わる名前のマクロは、引数リストの残りの項目をクォートする。 ‘o’ で終わる名前のマクロは一行以上にわたる入力のクォートを開始し、 これは対応する名前の ‘c’ でおわる名前のマクロで終了する。 囲みマクロはネストでき、引数は 8 つまで取れる。

注意: 拡張引数リストマクロ (‘.Xo’, ‘.Xc’) および関数の囲みマクロ (‘.Fo’, ‘.Fc’) は変則である。 拡張リストマクロはマクロの引数が troff の制限である 9 個を越えるときに用いられる。

UR マクロ (URI/URL ハイパーテキスト参照の開始), UE マクロ (終了), UN マクロ (参照用ターゲットの指定) も利用できる。 これらのマクロに関するより詳しい情報は man(7) を見よ。

ファイル
doc.tmac
    マニュアルドメインマクロと一般テキストドメインマクロ。
tmac/doc-common
    共通の構造マクロと定義。
tmac/doc-nroff
    サイト依存の nroff スタイルファイル。
tmac/doc-ditroff
    サイト依存の troff スタイルファイル。
tmac/doc-syms
    特殊定義 (標準マクロなど)。

関連項目
groff_mdoc(7), mdoc.samples(7), man(7), man-pages(7)

この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.51 の 一部である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。