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
’
に与えられたオプションがパーズされ、
中身の呼びだし可能なマクロである
‘
Fl
’
が呼ばれ、引数である
‘
s
’
に対して作用する。そして次に中身の呼びだし可能なマクロ
‘
Ar
’
が呼ばれ、引数である
‘
file
’
に作用する。呼びだし可能であるがパースされないマクロや、
その逆のマクロも存在する。このようなマクロは以下の
parsed カラムや
callable
カラムで示す。
特に記述がなければ、マニュアルドメインマクロは共通の書式をとる:
.Va argument
[ . , ; : ( ) [ ] argument
... ]
注意: 句読文字
(punctuation character)
の開き・閉じは、
それらが一度に単一の文字で現れた場合のみそのように解釈される。
文字列 ‘
),
’
は、句読区切りとはみなされず、その前に空白文字があれば
その文字とともに、また呼び出したマクロが用いるフォントで出力される。
引数リスト ‘
] )
,
’ は 3
つの連続した閉じ句読文字と解釈され、
それぞれの前にある空白文字は、各文字や
(もしあれば)
その前にある
引数との間には出力されない。
特殊な意味を持つ句読文字は、文字列
‘
\&
’
によってエスケープできる。
例えば以下の左の文字列は右のように変換される。
.Ar
file1 , file2 , file3 ) .
- → file1,
file2, file3).
マニュアルドメインマクロ¶
名前 |
Parsed |
Callable |
説明 |
Ad |
Yes |
Yes |
アドレス
(このマクロは使わない方が良い) |
An |
Yes |
Yes |
著者の名前 |
Ar |
Yes |
Yes |
コマンドライン引数 |
Cd |
No |
No |
設定の宣言
(セクション 4 のみ) |
Cm |
Yes |
Yes |
コマンドライン引数の修正子 |
Dv |
Yes |
Yes |
定義済み変数
(ソースコード) |
Er |
Yes |
Yes |
エラー番号
(ソースコード) |
Ev |
Yes |
Yes |
環境変数 |
Fa |
Yes |
Yes |
関数の引き数 |
Fd |
Yes |
Yes |
関数の宣言 |
Fn |
Yes |
Yes |
関数呼びだし
(.Fo と .Fc も) |
Ic |
Yes |
Yes |
インタラクティブなコマンド |
Li |
Yes |
Yes |
リテラルなテキスト |
Nm |
Yes |
Yes |
コマンドの名前 |
Op |
Yes |
Yes |
オプション
(.Oo と .Oc も) |
Ot |
Yes |
Yes |
古い形式の関数型
(Fortran のみ). |
Pa |
Yes |
Yes |
パス名またはファイル名 |
St |
Yes |
Yes |
標準
(-p1003.2, -p1003.1, -ansiC のどれか) |
Va |
Yes |
Yes |
変数の名前 |
Vt |
Yes |
Yes |
変数の型
(Fortran のみ) |
Xr |
Yes |
Yes |
マニュアルページの相互参照 |
一般テキストドメインマクロ¶
名前 |
Parsed |
Callable |
説明 |
%A |
Yes |
No |
参考文献の著者 |
%B |
Yes |
Yes |
参考文献の書籍タイトル |
%C |
No |
No |
参考文献の出版地
(街) |
%D |
No |
No |
参考文献の日付 |
%J |
Yes |
Yes |
参考文献の雑誌名 |
%N |
No |
No |
参考文献の号数 |
%O |
No |
No |
参考文献の補助情報 |
%P |
No |
No |
参考文献のページ |
%R |
No |
No |
参考文献のリポート名 |
%T |
Yes |
Yes |
参考文献の記事タイトル |
%V |
No |
No |
参考文献の巻数 |
Ac |
Yes |
Yes |
アングルクォートの閉じ |
Ao |
Yes |
Yes |
アングルクォートの開き |
Ap |
Yes |
Yes |
アポストロフィ |
Aq |
Yes |
Yes |
アングルクォート |
At |
No |
No |
AT&T UNIX |
Bc |
Yes |
Yes |
ブラケットクォートの閉じ |
Bf |
No |
No |
フォントモードの開始 |
Bo |
Yes |
Yes |
ブラケットクォートの開き |
Bq |
Yes |
Yes |
ブラケットクォート |
Bx |
Yes |
Yes |
BSD. |
Db |
No |
No |
デバッグ
(デフォルトは "off") |
Dc |
Yes |
Yes |
ダブルクォートの閉じ |
Do |
Yes |
Yes |
ダブルクォートの開き |
Dq |
Yes |
Yes |
ダブルクォート |
Ec |
Yes |
Yes |
エンクローズ文字列引用の閉じ |
Ef |
No |
No |
フォントモードの終了 |
Em |
Yes |
Yes |
強調
(traditional English). |
Eo |
Yes |
Yes |
エンクローズ文字列引用の開き |
Fx |
No |
No |
FreeBSD operating
system |
No |
Yes |
Yes |
通常のテキスト
(効果なし) |
Ns |
Yes |
Yes |
スペース無し |
Pc |
Yes |
Yes |
括弧クォートの閉じ |
Pf |
Yes |
No |
前置文字 |
Po |
Yes |
Yes |
括弧クォートの開き |
Pq |
Yes |
Yes |
括弧クォート |
Qc |
Yes |
Yes |
ダブルストレートクォートの閉じ |
Ql |
Yes |
Yes |
クォートされたリテラル |
Qo |
Yes |
Yes |
ダブルストレートクォートの閉じ |
Qq |
Yes |
Yes |
ダブルストレートクォートの閉じ |
Re |
No |
No |
参考文献の終了 |
Rs |
No |
No |
参考文献の開始 |
Rv |
No |
No |
返り値
(セクション 2, 3 のみ) |
Sc |
Yes |
Yes |
シングルクォートの閉じ |
So |
Yes |
Yes |
シングルクォートの開き |
Sq |
Yes |
Yes |
シングルクォート |
Sm |
No |
No |
スペースモード
(デフォルトは "on") |
Sx |
Yes |
Yes |
セクションの相互参照 |
Sy |
Yes |
Yes |
シンボリック
(traditional English). |
Tn |
Yes |
Yes |
Trade
または型名 (small Caps). |
Ux |
Yes |
Yes |
UNIX |
Xc |
Yes |
Yes |
拡張引数リストの閉じ |
Xo |
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.41 の
一部である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man-pages/
に書かれている。