mdoc(1) Macro Package

書式

groff -m doc files ...

説明

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

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

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

ページ構造のドメイン

タイトルマクロ

正しいマニュアルページを生成するためには、これらの 3 つのマクロを この順番で書く必要がある。

. Month day, year
文書の日付。
.
タイトルを大文字で。
. OPERATING_SYSTEM [version/release]
オペレーティングシステム (BSD )

ページレイアウトマクロ

セクションヘッダ、段落の終わり、リスト、表示など。

.

セクションのヘッダ。 正しいヘッダは、現れる順に:

NAME
名前のセクション。 `. ' , `.Fn , ' `. - などのマクロを含む。 '
SYNOPSIS
利用法。
DESCRIPTION
一般的な説明。オプションやパラメータの説明も含む。
RETURN VALUE
セクション 2 や 3 の関数コール。
ENVIRONMENT
環境変数を説明する。
FILES
内容に関係するファイル。
EXAMPLES
例やおすすめ。
DIAGNOSTICS
通常セクション 4 のデバイスインターフェースの診断用。
ERRORS
セクション 2 や 3 のエラーやシグナル処理。
SEE ALSO
相互参照や引用。
CONFORMING TO
可能なら標準への準拠。
HISTORY
標準が適用されていない場合は、 歴史的な内容を与えるべきである。
BUGS
瑕疵や警告。
other
筆者の判断でヘッダをあつらえてもよい。

Li .Ss サブセクションのヘッダ。 Li .Pp 段落の区切り。 垂直スペース (一行)。 Li .D1 (D-one) Display-one インデントしてテキストを一行表示。 Li .Dl (D-ell) Displey-one literal。 インデントしてリテラルなテキストを一行表示。 Li .Bd 表示ブロックの開始。 表示オプション:

-ragged
揃えない (両端は不揃い)。
-filled
揃える。
-literal
リテラルなテキストまたはコード。
-file name
指定された file を読んで表示する。
-offset string
オフセット表示。 受付ける string の値は:

left
ブロックを左に揃える (デフォルト)。
center
大まかなセンターマージン。
indent
定数幅の空白 6 つ (タブ 1 つ)。
indent-two
タブ 2 つ。
right
揃えブロックを右から 2 インチの位置に残す。
xx n
xx4 n から 99 n までの数字。
Aa Aa は呼びだし可能なマクロの名前。
string
string の幅が用いられる。

Li .Ed 表示終了 (.Bd にマッチする)。 Li .Bl リスト開始。 リストまたはコラムを生成する。オプションは以下:

リスト形式

-bullet Ta 中黒のアイテムリスト
-item Ta ラベルなしリスト
-enum Ta 数値付きリスト
-tag Ta タグラベル付きリスト
-diag Ta 診断リスト (diagnostic list)
-hang Ta ぶらさがりラベルリスト
-ohang Ta 飛び出しラベルリスト
-inset Ta ラベル付きリストの挿入・継続

リストパラメータ

-offset
(全てのリスト) 上記の `. ' ディスプレイ開始 (begin-display) を見よ。
-width
( -tag および -hang リストのみ) `. ' を見よ。
-compact
(全てのリスト) 空行を抑制する。

Li .El リストの終わり。 Li .It リスト項目。

マニュアルドメインマクロと一般テキストドメインマクロ

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

.[-s file ]
→ [-s file ]

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

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

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

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

.file1 , file2 , file3 ) .
file1 , file2 , file3 )

マニュアルドメインマクロ

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

一般テキストドメインマクロ

名前        Parsed  Callable        説明
%A Ta Yes Ta Ta 参考文献の著者
%B Ta Yes Ta Yes Ta 参考文献の書籍タイトル
%C Ta Ta Ta 参考文献の出版地 (街)
%D Ta Ta Ta 参考文献の日付
%J Ta Yes Ta Yes Ta 参考文献の雑誌名
%N Ta Ta Ta 参考文献の号数
%O Ta Ta Ta 参考文献の補助情報
%P Ta Ta Ta 参考文献のページ
%R Ta Ta Ta 参考文献のリポート名
%T Ta Yes Ta Yes Ta 参考文献の記事タイトル
%V Ta Ta Ta 参考文献の巻数
Ac Ta Yes Ta Yes Ta アングルクォートの閉じ
Ao Ta Yes Ta Yes Ta アングルクォートの開き
Ap Ta Yes Ta Yes Ta アポストロフィ
Aq Ta Yes Ta Yes Ta アングルクォート
AT&T System Ta Ta Ta AT&T UNIX
Bc Ta Yes Ta Yes Ta ブラケットクォートの閉じ
Bf Ta Ta Ta フォントモードの開始
Bo Ta Yes Ta Yes Ta ブラケットクォートの開き
Bq Ta Yes Ta Yes Ta ブラケットクォート
BSD Ta Yes Ta Yes Ta BSD
Db Ta Ta Ta デバッグ (デフォルトは "off")
Dc Ta Yes Ta Yes Ta ダブルクォートの閉じ
Do Ta Yes Ta Yes Ta ダブルクォートの開き
``Ta Yes Ta Yes Ta ダブルクォート ''
Ec Ta Yes Ta Yes Ta エンクローズ文字列引用の閉じ
Ef Ta Ta Ta フォントモードの終了
Ta Yes Ta Yes Ta 強調 (traditional English).
Eo Ta Yes Ta Yes Ta エンクローズ文字列引用の開き
Fx Ta Ta Ta FreeBSD operating system
Ta Yes Ta Yes Ta 通常のテキスト (効果なし)
Ta Yes Ta Yes Ta スペース無し
Pc Ta Yes Ta Yes Ta 括弧クォートの閉じ
Ta Yes Ta Ta 前置文字
Po Ta Yes Ta Yes Ta 括弧クォートの開き
(Ta Yes Ta Yes Ta 括弧クォート )
Qc Ta Yes Ta Yes Ta ダブルストレートクォートの閉じ
`Ta Yes '
Ta Yes Ta クォートされたリテラル
Qo Ta Yes Ta Yes Ta ダブルストレートクォートの閉じ
Qq Ta Yes Ta Yes Ta ダブルストレートクォートの閉じ
Li Rs Ta No Ta No Ta 参考文献の開始 Li Rv Ta No Ta No Ta "返り値 (セクション 2, 3 のみ)" Li Sc Ta Yes Ta Yes Ta シングルクォートの閉じ Li So Ta Yes Ta Yes Ta シングルクォートの開き Li Sq Ta Yes Ta Yes Ta シングルクォート Li Sm Ta No Ta No Ta "スペースモード (デフォルトは "on")" Li Sx Ta Yes Ta Yes Ta セクションの相互参照 Li Sy Ta Yes Ta Yes Ta "シンボリック (traditional English)." Li Tn Ta Yes Ta Yes Ta "Trade または型名 (small Caps)." Li Ux Ta Yes Ta Yes Ta Ux Li Xc Ta Yes Ta Yes Ta 拡張引数リストの閉じ Li Xo Ta Yes Ta Yes Ta 拡張引数リストの開き

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

注意: 拡張引数リストマクロ ( `. ' `. ' および関数の囲みマクロ ( `.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
特殊定義 (標準マクロなど)。

この文書について

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