マニュアル領域

アドレスマクロ

アドレスマクロは addr1[,addr2[,addr3]] の形式からなる アドレスを識別します。

使い方: .address ... [ .,:;()[]?! ]

.addr1

addr1

.addr1

addr1

.addr1 , file2

addr1 , file2

.f1 , f2 , f3:

f1 , f2 , f3

.addr ) ),

addr ) ),

`.を引数なしで呼び出すのはエラーです。 ' `.は他のマクロから呼び出し可能で解析されます。 '

作者名

`.An マクロは文書化されている項目の作者の名前、もしくは実際の ' マニュアルページの作者の名前を指定するために使われます。 名前の情報の後のすべての引数は句読点として扱われます。

使い方: .An author_name [ .,:;()[]?! ]

.An Joe Author

An Joe Author

.An Joe Author,

An Joe Author ,

.An Joe Author Aq [email protected]

An Joe Author Aq [email protected]

.An Joe Author ) ),

An Joe Author ) ),

`.An マクロは解析され、呼び出し可能です。 ' `.An を引数なしで呼び出すのはエラーです。 '

引数マクロ

引数マクロ `.file ... ' はコマンド行の引数を参照する際に 使用することができます。

使い方: .argument ... [ .,:;()[]?! ]

.file ...

file ...

.file1

file1

.file1

file1

.file1 file2

file1 file2

.f1 f2 f3:

f1 f2 f3

.file ) ),

file ) ),

`.file ... ' が引数なしで呼び出されると、 `.file ... ' として扱われます。 `.file ... ' マクロは解析され、呼び出し可能です。

コンフィギュレーション宣言 (セクション 4 のみ)

`.マクロはセクション ' 4 のマニュアルにおいて、 デバイスインタフェースの config(8) による宣言の説明に使われます。 このマクロは引用符 (二重引用符のみ) で囲まれた引数を取ることができます。

device le0 at scode?

は `.device ' le0 at scode? によって生成されます。

コマンド修飾子

コマンド修飾子は `.マクロがすべての引数の前にダッシュ文字を ' 付けないことを除いて、 `.- ' (フラグ) コマンドと同じです。 伝統的にフラグはダッシュ文字に引き続いて指定されますが、 いくつかのコマンドやコマンドのサブセットはこの方法を使っていません。 コマンド修飾子はエディタコマンドのような対話的なコマンドでも 指定されることがあります。 Sx フラグ のセクションを参照してください。

定義済みの変数

インクルードファイルにおいて定義されている変数は `.マクロによって指定します。 '

使い方: .defined_variable ... [ .,:;()[]?! ]

.MAXHOSTNAMELEN

MAXHOSTNAMELEN

.TIOCGPGRP )

TIOCGPGRP

`.を引数なしで呼び出すのはエラーです。 ' `.は解析され、呼び出し可能です。 '

errno (セクション 2 のみ)

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

使い方: .Er ERRNOTYPE ... [ .,:;()[]?! ]

.Er ENOENT

Er ENOENT

.Er ENOENT );

Er ENOENT ) ;

.Bq Er ENOTDIR

Bq Er ENOTDIR

`.Er を引数なしで呼び出すのはエラーです。 ' `.Er は解析され、呼び出し可能です。 '

環境変数

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

使い方: .argument ... [ .,:;()[]?! ]

.DISPLAY

DISPLAY

.PATH

PATH

.PRINTER ) ),

PRINTER ) ),

`.を引数なしで呼び出すのはエラーです。 ' `.は解析され、呼び出し可能です。 '

関数の引数

`.Fa マクロは関数の引数 ' (パラメータ) を マニュアルの Sx SYNOPSIS のセクション外、 もしくは Sx SYNOPSIS のセクション内で参照する場合に使われます。 パラメータのリストが `.Fn マクロでは長すぎる場合は、 ' 囲って使うマクロ `.Fo と ' `.Fc を使わなければなりません。 ' `.Fa は構造体のメンバを参照する場合にも使われます。 '

使い方: .Fa function_argument ... [ .,:;()[]?! ]

.Fa d_namlen ) ),

Fa d_namlen ) ),

.Fa iov_len

Fa iov_len

`.Fa を引数なしで呼び出すのはエラーです。 ' `.Fa は解析され、呼び出し可能です。 '

関数の宣言

`.Fd マクロは ' Sx SYNOPSIS セクションにおいて、 セクション 2 または 3 の関数の説明で使われます。 `.Fd マクロから他のマクロを呼び出すことはなく、 ' 他のマクロから呼び出すこともできません。

使い方: .Fd include_file (or defined variable)

Sx SYNOPSIS セクションにおいて、関数がすでに示されていて改行が 入っていない場合、 `.Fd によって改行が挿入されます。これによって ' 前の関数呼び出しと次の関数の宣言の間に最適な行間が設定されます。

フラグ

`.- ' マクロはコマンド行のフラグを扱います。 フラグの前にはダッシュ `-' が挿入されます。 対話的なコマンドのフラグでは、ダッシュがフラグの前には挿入されませんが、 `.(コマンド修飾子) ' マクロは、ダッシュを付けないことを除き、 同じ働きをします。

使い方: .-argument ... [ .,:;()[]?! ]

.-

-

.-cfv

-cfv

.-cfv

-cfv

.-s v t

-s v t

.--,

--

.-xyz ),

-xyz )

引数なしで `.- ' マクロを指定すると、 標準入力/標準出力を意味するダッシュとなります。 ひとつのダッシュに `.- ' マクロを使用すると、 2 つダッシュとなることに注意して下さい。 `.- ' マクロは解析され、呼び出し可能です。

関数 (ライブラリルーチン)

`.Fn マクロは ' ANSI C の記法を規範としています。

使い方: .Fn [type] function [[type] parameters ... [ .,:;()[]?! ]]

.Fn getchar

Fn getchar

.Fn strlen ) ,

Fn strlen ) ,

.Fn "int align" "const * char *sptrs"

Fn int align const * char *sptrs ,

`.Fn を引数を指定せずに呼び出すのはエラーです。 ' `.Fn マクロは解析され、呼び出し可能です。 ' 他のマクロの呼び出しは `.Fn の呼び出しの終了を意味することに ' 注意して下さい (閉じ括弧がその点で挿入されます)。

9 個以上のパラメータをとる関数 (これは滅多にないことですが) では、 `.Fo マクロ ' (関数オープン) と `.Fc マクロ ' (関数クローズ) を `.Fa (関数引数) ' と共に使って、 この制限を回避することができます。 以下にその例を示します。

.Fo "int 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

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

Fo int 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

`.Fo と ' `.Fc マクロは解析され、呼び出し可能です。 ' Sx SYNOPSIS セクションでは、関数は常に行の先頭から開始されます。 Sx SYNOPSIS セクションにおいて、複数の関数が示されており、 関数の型が示されない場合、改行が挿入され、現在の関数名とその前の関数名 の間に最適な改行量が設定されます。現在、 `.Fn は ' troff の行の長さ に対して、語の境界をチェックしておらず、予期しない場所で改行が挿入され てしまうことがあります。これは近い将来修正されるでしょう。

関数の型

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

使い方: .Ft type ... [ .,:;()[]?! ]

.Ft struct stat

Ft struct stat

`.Ft は他のマクロからは呼び出せません。 '

対話的なコマンド

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

使い方: .argument ... [ .,:;()[]?! ]

.:wq

:wq

.do while {...}

do while {...}

.setenv , unsetenv

setenv , unsetenv

`.を引数なしで呼び出すのはエラーです。 ' `.マクロは解析され、呼び出し可能です。 '

名前マクロ

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

使い方: .argument ... [ .,:;()[]?! ]

.mdoc.sample

mdoc.sample

.\-mdoc

-mdoc

.foo ) ),

foo ) ),

.

`. ' マクロは解析され、呼び出し可能です。

オプション

`.[マクロはコマンド行の残りのすべての引数をオプションである] ' ことを示す角括弧で囲み、末尾の句読点は角括弧の外に置きます。 `.] ' マクロと `.[マクロは複数行に渡って使うことが ' できます。

使い方: .[options ... [ .,:;()[]?! ]]

.[[

.[-k ]

] ]

[-k ]

.[-k ) . ]

[-k ]

.[-k kookfile ]

[-k kookfile ]

.[-k kookfile , ]

[-k kookfile ]

.[objfil [corfil ] ]

[objfil [corfil ] ]

.[-c objfil [corfil , ] ]

[-c objfil [corfil ] ]

.[word1 word2]

[word1 word2]

`.] ' マクロと `.[マクロ: '

.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc

生成結果: [[-k kilobytes ] [-i interval ] [-c count ] ]

`.[と] ' `.] ' と `.[マクロは ' 解析され、呼び出し可能です。

パス名

`.マクロはパス名もしくはファイル名をフォーマットします。 '

使い方: .pathname [ .,:;()[]?! ]

./usr/share

/usr/share

./tmp/fooXXXXX )

/tmp/fooXXXXX )

`.マクロは解析され、呼び出し可能です。 '

変数

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

使い方: .variable ... [ .,:;()[]?! ]

.count

count

.settimer

settimer

.int *prt ):

int *prt )

.char s ] ) ),

char s ] )),

`.を引数なしで呼び出すのはエラーです。 ' `.マクロは解析され、呼び出し可能です。 '

マニュアルページの相互参照

`.マクロは最初の引数にマニュアルページの名称を取り、 ' もしあれば次の引数にセクションのページ数か句読点を取ります。 すべての残りの引数は句読点と見なされます。

使い方: .man_page[1,...,8][ .,:;()[]?! ]

.mdoc

mdoc

.mdoc

mdoc,

.mdoc(7)

mdoc(7)

.mdoc(7)))

mdoc(7))),

`.マクロは解析され、呼び出し可能です。 ' `.を引数なしで呼び出すのはエラーです。 '

一般テキスト領域

AT&T マクロ

使い方: .At [v6 | v7 | 32v | V.1 | V.4] ... [ .,:;()[]?! ]

.AT&T System

AT&T System

.AT&T System v6 .

AT&T System v6 .

`.AT&T System ' マクロは解析 されず 、呼び出し 不可 です。 最大 2 つまでの引数を取ることができます。

BSD マクロ

使い方: .BSD [Version/release] ... [ .,:;()[]?! ]

.BSD BSD

.BSD 4.3 .

BSD 4.3

`.BSD マクロは解析され、呼び出し可能です。 '

FreeBSD マクロ

使い方: .Fx Version.release ... [ .,:;()[]?! ]

.Fx 2.2 .

Fx 2.2 .

`.Fx マクロは解析 ' されず 、呼び出し 不可 です。 最大 2 つまでの引数を取ることができます。

UNIX マクロ

使い方: .UNIX

.UNIX

UNIX

`.UNIX ' マクロは解析され、呼び出し可能です。

囲い/クォートマクロ

囲いの概念はクォートと似たものです。 1 つ以上の文字列が引用符や括弧のような文字のペアで囲まれている オブジェクトを指します。 クォートと囲いという用語はこの文書を通して同じ意味で使われます。 ほとんどの 1 行の囲いマクロはクォート (quote) のヒントとするために、 小文字の `q' で終了しますが、いくつかの例外があります。 各々の囲いマクロに対し、開始マクロと終了マクロのペアもあり、 それぞれ小文字の `o' と `c' で終了します。 これらは 1 行以上のテキストに渡って使うことができますが、 入れ子にする場合に制限があります。 その中では 1 行形式のクォートマクロのみ使用することができます。

クォート  終了  開始  機能  結果 .Aq    .Ac     .Ao     カギ括弧による囲い<文字列>
.Bq     .Bc     .Bo     角括弧による囲い        [文字列]
.Dq     .Dc     .Do     二重引用符 ``文字列''
        .Ec     .Eo     囲い文字列 (XXによる)   XX文字列XX
.Pq     .Pc     .Po     括弧による囲い   (文字列)
.Ql                     クォートされたリテラル       `st' or 文字列
.Qq     .Qc     .Qo     まっすぐな二重引用符  "文字列"
.Sq     .Sc     .So     一重引用符 `文字列'

下記の不正なマクロを除き、すべてのクォートマクロは解析され、呼び出し 可能です。句読点がひとつずつ置かれていて、スペースで区切られていれば、 すべてのクォートマクロは句読点を適切に扱います。クォートマクロは開く 句読点、閉じる句読点(訳注: 句読点には括弧なども含みます) を調べ、 それが囲む文字列より前か後かを決めます。これによって、ある程度の入れ子 が可能になっています。

.Ec , .Eo これらのマクロは各々開始および終了の文字列を最初の引数に取ります。

.`リテラルをクォートするマクロは'

troff では nroff と異なっ た処理を行ないます。 nroff でフォーマットされた場合、クォート指定 されたリテラルは常にクォートされます。 troff でフォーマットされた 場合は、アイテムの幅が固定幅文字 3 つ分より狭い場合にのみクォートされま す。これはリテラル (固定幅) のフォントの変更があまり気づかれないもので あるため、短い文字列を良く見えるようにするためです。

.プレフィックスマクロは呼び出し可能ではありませんが、解析されます。

.( Fa name2

は ( Fa name2 となります。

`.(空白なし) ' マクロはサフィックス機能と同様の作用があります。

クォートの例:

.Aq Aq

.Aq ctype.h ),

Aq Ar ctype.h ) ,

.Bq Bq

.Bq Greek , French .

Bq Em Greek , French .

.````

.``string abc .''

'' ''

``string abc''

.``'^[A-Z]'''

``'^[A-Z]'''

.`man'

mdoc `man' mdoc

.Qq Qq

.Qq string ) ,

Qq string ) ,

.Qq string ),

Qq string Ns ),

.``

.`string'

' '

`string'

囲いマクロの入れ子についての良い例については、 オプションマクロ `.[を参照してください。] ' このマクロは上でリストされているような囲いマクロと同じベースの上に 作られています。 拡張引数リストマクロ `. ' と `. ' もまた同じルーチンを ベースに作られており、 -mdoc マクロの使い方の非常に良い例と なっています。

no-op もしくは通常テキストマクロ

`.マクロはマクロコマンド行において、コンテントマクロの構文 ' 形式に従うが、フォーマットされては ならない 単語をハックする ものです。

空白なしマクロ

`.マクロはマクロ間での不要な空白を除去します。 ' これはフラグと引数の間に空白を含まない古いスタイルの引数リストを使う 場合に便利です。

.[-I directory ]

は [-I directory ] という結果になります。

注: `.マクロは他のマクロ名が続かなければ、 ' スペースを除去したあとに `.マクロを常に起動します。 ' `.マクロは解析され、呼び出し可能です。 '

セクションの相互参照

`.Sx マクロは同一文書内でのセクションのヘッダへの参照を ' 指定します。これは解析され、呼び出し可能です。

.Sx FILES

Sx FILES

相互参照と引用

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

.

参考文献の開始。 改行を挿入してから、参考文献の終了マクロが読み込まれるまで 参考文献の情報を収集する。 Li .Re 参考文献の終了。参考文献が表示される。 Li .%A 参考文献の作者名。1 回の呼び出しにつき、作者名をひとつ指定する。 Li .%B 書籍のタイトル。 Li .%C 都市/場所。 Li .%D 日付。 Li .%J 定期刊行物の名称。 Li .%N 発行番号。 Li .%O 追加の情報。 Li .%P ページ番号。 Li .%R 報告書の名称。 Li .%T 記事のタイトル。 Li .%V 巻数。

`%' で始まるマクロは呼び出し不可能ですが、 呼び出し側に戻る商標名マクロだけは解析されます。 (現時点では予期できないことです。) 商標名のみ解析されるのは troffNs/NsXrditroff の出力を きれいにするためです。

返り値

`.Rv マクロは ' Sx RETURN VALUE のセクション で使うテキストを生成します。

使い方: .Rv [-std function]

`.Rv -std ' atexit は以下のテキストを生成します。

Rv -std atexit

-std オプションはセクション 2 と 3 のマニュアルページでのみ有効です。

商標名 (頭文字とタイプ名)

商標名マクロは一般的に長さが 2 文字を越えるすべてが大文字の単語用に 使われる小さな大文字のマクロです。

使い方: .symbol ... [ .,:;()[]?! ]

.DEC

DEC

.ASCII

ASCII

`.マクロは解析され、他のマクロから呼び出し可能です。 '

拡張引数

`. ' と `. ' マクロでマクロの境界における引数リストを 拡張することができます。引数リストは `.[のようなすべての引数] ' が 1 行中に指定されていることを前提としているマクロの中では行に渡って 拡張することができません。

以下に空白モードマクロをスペーシングをオフにするために 使った `. ' での例を示します。

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

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

I operation \n count \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 ]

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

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

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

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

上のすべての例では `. ' (リスト項目) マクロの 引数リストに `. ' マクロを使用しています。 拡張マクロが使われることはあまりありません。使われるとすれば、リスト 項目の引数リストを拡張する場合です。残念なことに、これが拡張マクロが 最も懲り性であるところでもあります。最初の 2 つの例では、スペーシングは オフになっています。3 番目では、ある箇所にはスペーシングを入れることが 望ましいのですが、出力全体に入れたいわけではありません。そのような状況 でこれらのマクロが適切に動作するためには、 `. ' と `.

' マクロが

3 番目の例にあるように指定されていることを確認してください。 `. ' マクロが置かれた `. ' の引数リストに他のものが 置かれると、スペーシングがどうなるかは予測不可能です。 この場合、 `.(空白なしマクロ) ' は行中の最初もしくは最後の マクロに指定してはいけません。現在 BSD でリリースされている 900 の マニュアルページ (実際のページでは約 1500 ページ) のうち 15 の マニュアルページでのみしか `. ' が使われていません。

ページ構造のドメイン

セクションヘッダ

以下にリストされている、最初の 3 つのセクションヘッダマクロ `.

はすべての

' man ページで必須のものです。 残りのセクションヘッダはマニュアルページの作者の裁量において、 推奨されているものです。 `.

マクロは

' 9 つまでの引数を取ることができます。 これは解析されますが、呼び出し不可能です。

.

名前

名前

(NAME) マクロは必須のものです。 これが指定されていないと、ヘッダとフッタ、それにデフォルトの ページレイアウトが設定されず、結果はかなり好ましくないものになるでしょう。 Sx NAME セクションは最低 3 つの項目からなります。 最初のものは名称マクロ `. ' であり、man ページのサブジェクトと なります。2 番目のものは名称説明マクロ `. - であり、 ' サブジェクト名を 3 つめの項目、すなわちその名称の説明と分離します。 説明に割り当てられるスペースは小さいものですので、 できるだけ簡潔で分かりやすいものでなければなりません。 .Sh 書式 Sx 書式 (SYNOPSIS) セクションはその man ページのサブジェクト となっている項目の典型的な使用法を説明します。 必須のマクロは `.Nm' , `.Cd' , `.Fn' のいずれかです。 (他には `.Fo' , `.Fc' , `.Fd' , `.Ft' の マクロも必要な場合があります。) 関数名マクロ `.Fn' はセクション 2 と 3 のマニュアルページに おいて必須のもので、コマンドと一般名称マクロ `. ' は セクション 1, 5, 6, 7, 8 で必須の項目です。 セクション 4 のマニュアルでは `.Nm' か `.Fd' 、もしくは コンフィギュレーションデバイス使用法マクロ `.Cd' が必要です。 その他のいくつかのマクロが下に示すような書式行を生成するために必要な ことがあります。

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

以下のマクロが使われています。

.cat

.[-benstuv ]

.[- ]

.file ...

注 マクロ `.[,] ' `.- ' `.file ... ' は パイプの文字 `|' を認識し、下記のようなコマンド行

".[-a | -b ]

はうまくいきません。 troff は通常 | を特別のオペレータとして 解釈します。この他で | が使える場合については Sx 定義済みの文字列 セクションを参照して下さい。

.

説明

Sx 説明 (DESCRIPTION) セクションでの最初のテキストは、 ほとんどの場合ではそのコマンド、関数もしくはファイルについての短い 段落で、オプションの構文リストとそれぞれの説明がそれに続きます。 そのようなリストを作成するには リスト開始マクロ `.

' 、リスト項目マクロ `.

、 ' リスト終了マクロ `.

' を使います (後述の Sx リストと列 セクションを参照)。

以下の `.

のセクションヘッダはマニュアルページの好ましい

' レイアウトの一部であり、一貫性を保つために適切に使われなければ なりません。これらは使われる順番にリストされています。

.

環境変数

Sx 環境変数 (ENVIRONMENT) セクションは関連する環境変数を明らかにし、 それらの振舞いや使用方法を示します。 .Sh 例 使用例、実行例を作成するには様々な方法があります。 詳細については、下の Sx 例 のセクションを参照してください。 .Sh ファイル

man ページのサブジェクトによって使用されるか生成されるファイルで、 Sx ファイル のセクション中でマクロ `.によってリスト ' されます。 .Sh 関連項目 Sx 関連項目 (SEE ALSO) セクションには、その man ページの題材に 関する資料への参照と他の関連する man ページへのクロスリファレンスが 記載されます。クロスリファレンスは `.マクロによって指定 ' されます。 Sx 関連項目 セクションでのクロスリファレンスは セクション番号順に並べ、セクション中ではカンマで区切って アルファベット順に並べなければなりません。以下に例を示します。

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

ここで参考スタイルである refer(1) は適応されていません。 .Sh 準拠 コマンドやライブラリ関数やファイルが、 St -p1003.2 や St -ansiC のような特定の実装によるものであれば、ここで記述します。 コマンドがどの規格にも基づいていなければ、その歴史は Sx 歴史 (HISTORY)のセクションで説明されなければなりません。 .Sh 歴史 特定の規格に基づいていないコマンドは、 このセクションでその歴史の概要が説明されるべきです。 .Sh 作者 クレジットが必要であれば、ここで入れます。 .Sh 診断 コマンドからの診断はこのセクションに入れます。 .Sh エラー 特定のエラーハンドリング、特にライブラリ関数 (man ページのセクション 2, 3, 9) でのエラーハンドリングは、ここで説明します。 `.Er マクロが ' errno を記述するために使われます。 .Sh バグ あきらかな問題はここで記述します...

ユーザ指定の `.

セクションを追加することができます。

' たとえば、このセクションは以下のように設定されています。

.Sh ページ構造領域

段落と行スペース

.

`.

' 段落コマンドは必要な場合に行スペースを指定するために使われます。 このマクロは、 `.

マクロや

' `.

マクロの後や、

' `.

' マクロの前では必要ありません。 ( `.

' マクロは -compact フラグが指定されていなければ、 縦方向の距離を宣言します)。

キープ

現在実装されているキープは単語に対するものだけです。 それらは `.(キープ開始) ' マクロと `.(キープ終了) ' マクロです。 `.に指定できるオプションは ' -words のみで あり、これはオプションの途中で改行が入らないようにするのに便利です。 コマンド行の引数を生成する例 ( Sx この名前には何が...? セクションを 参照) において、キープは nroff がフラグと引数を別の行に分けない ように使われています。 (実際には、オプションマクロがこの目的で使われて いましたが、オプションが行中にわたって散らばってしまうと一般的に見栄え が悪くなるという理由により troff で右揃えのマージンを強制的に 行なう (宗教的な) 決定がなされてから、オプションマクロをこの目的で 使わないようになりました。キープマクロについてはもっと機能を向上する 作業が必要であり、 -line オプションを追加していく必要があります。)

例やディスプレイ

ディスプレイには 5 つのタイプがあります。 即席 1 行インデントディスプレイ `.D1' 、 即席 1 行リテラルディスプレイ `.

、それに

' ディスプレイ開始マクロ `. ' と ディスプレイ終了マクロ `. ' を使用する リテラルブロック、フィルブロックおよび凸凹ブロックです。

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

-ldghfstru

これは次の指定で生成されます: .

-ldghfstru

.

(D-エル) インデントされた リテラル テキストを 1 行表示します。 `.

マクロの例は本ファイルの中に渡って使われています。

' これによって 1 行のテキストのインデント (表示) が可能になります。 このマクロは解析され、他のマクロを認識することができますが、 デフォルトのフォントは固定幅 (リテラル) にセットされています。 しかしながら、呼び出しは不可能です。

% ls -ldg /usr/local/bin

これは次の指定で生成されます: .

% ls -ldg /usr/local/bin

. ディスプレイ開始です。 `. ' によるディスプレイは `. ' マクロによって 終了しなければなりません。 ディスプレイはディスプレイ内およびリスト内で入れ子にすることができます。 `. ' は以下の書式をとります。

".

ディスプレイタイプは以下の 4 つのタイプの内の 1 つでなければならず、 インデント `. ' のオフセット値を指定することができます。

-ragged テキストのブロックをタイプされた通りに表示します。 右マージン (と左マージン) のエッジは左に不揃いに寄せられます。

-filled フィル (フォーマット) されたブロックを表示します。 テキストのブロックがフォーマットされます (エッジは左非揃えではなく、フィルされます)。

-literal リテラルなブロックを表示します。ソースコードや、単純にタブもしくは スペースで整えられたテキストで便利です。

-file ファイル名 -file フラグに続く名称のファイルが読み込まれ、表示されます。表示 はリテラルなモードで行われ、タブは定幅文字 8 つ分に固定されますが、 ファイル中のすべての troff/NsNm-mdoc コマンドは解釈されます。

-offset string -offset が以下の文字列のいずれかとともに指定されていると、 その文字列は次のテキストのブロックのインデントのレベルを示すものとして 解釈されます。

left ブロックを現在の左マージンに揃えます。 これは `. ' のデフォルトのモードです。

center ブロックを中央揃えにします。残念ながら現時点では、 単にブロックの左側を仮想的な中央マージンに揃えるだけです。

indent デフォルトのインデント値もしくはタブの分だけインデントします。 デフォルトのインデント値はディスプレイ `.D1' でも使われ、 これら 2 つのタイプのディスプレイを使った場合、 行が揃うことが保証されています。 このインデントは通常 6n か約 2/3 インチ (定幅文字 6 つ分) です。

indent-two デフォルトのインデント値の 2 倍分インデントします。

right これはブロックをページの右端から約 2 インチ離して 左 揃えします。このマクロはちゃんと動作する必要があるのですが、 troff ではまったくちゃんと動作してくれていません。

. ディスプレイ終了。

フォントモード

マニュアルページのテキストの見栄えを変更するマクロは 5 つあります。

.テキストは `.マクロで強調することができます。 ' 強調の場合、通常イタリック体のフォントが使われます。

使い方: .argument ... [ .,:;()[]?! ]

.does not does not

.exceed 1024 . exceed 1024

.vide infra ) ) , vide infra ) ),

`.マクロは解析され、呼び出し可能です。 ' `.を引数なしで呼び出すのはエラーです。 '

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

使い方: .argument ... [ .,:;()[]?! ]

.\en \n

.M1 M2 M3; M1 M2 M3

.cntrl-D ), cntrl-D )

.1024 ... 1024 ...

`.マクロは解析され、呼び出し可能です。 '

.シンボリック体強調マクロはシンボリックの意味でも 伝統的な英語の使いかたにおいても、 通常はボールドマクロとなっています。

使い方: .symbol ... [ .,:;()[]?! ]

.Important Notice Important Notice

`.マクロは解析され、呼び出し可能です。 ' `.の引数は引用符で囲むことができます。 '

.Bf フォントモード開始。 フォントモード `.Bf は ' `.Ef マクロで ' 終了しなければなりません。 フォントモードは他のフォントモードと入れ子にすることができます。 `.Bf は次の構文を取ります。 '

".Bf font-mode

font-mode は以下の 3 つのタイプのうちのいずれかでなければなりません。

| -emphasis 強調モード。 `.マクロがテキストブロック全体に使われているのと同様です。 '

| -literal リテラルモード。 `.マクロがテキストブロック全体に使われているのと同様です。 '

| -symbolic シンボリックモード。 `.マクロがテキストブロック全体に使われているのと同様です。 '

.Ef フォントモードの終了。

タグ付きリストと列

リスト開始マクロ `.Bl' で開始されるリストにはいくつかのタイプが あります。リスト中の項目は項目マクロ `.It' で指定され、各リスト は `.El' マクロで終了しなければなりません。リストはリスト自身や ディスプレイの中で入れ子にすることができます。列はリストの中で使うこと ができますが、リストが列の中で使えるかどうかは検証されていません。

さらに、タグの幅、リストのオフセット、コンパクトさ(項目間の空白行が 許されているかどうか) のような、いくつかのリストの属性を指定することが できます。本ドキュメントのほとんどはタグ (-tag ) スタイルリストで フォーマットされています。各種リストタイプは、調子を変えるために オーバーハング (-ohang ) でリストしました。 このリストのタイプは TeX のユーザに非常に人気のあるものですが、

tag リストで構成されたページを何ページも読んだ後には幾分変に見える でしょう。以下のリストタイプを `.Bl' で使うことができます。

-bullet

-item

-enum これら 3 つは最も単純なリストのタイプです。 一旦 `.Bl' マクロが与えられると、リスト中の項目は 単に `.It' マクロによってのみ構成される行で指定されます。 例として、簡単な列挙リストのソーステキストは、このようになります。

.Bl -enum -compact
.It
ひとつめはここ。
.It
そしてふたつめ。
.It
最後にみっつめはここ。
.El

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

1. ひとつめはここ。
2. そしてふたつめ。
3. 最後にみっつめはここ。

簡単な bullet リスト構成の例を示します。

.Bl -bullet -compact
.It
ひとつめの bullet。
.It
これはふたつめの bullet。
.El

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

• ひとつめの bullet。
• これはふたつめの bullet。

-tag

-diag

-hang

-ohang

-inset これらのリストタイプは `.

マクロによって指定されている引数 ' からラベルを生成します。 そして、 inset では、次のテキストへそのラベルを挿入します。 hang では、次のテキストをラベルの位置へインデントします。 ohang (オーバーハング) では、次のテキストをラベルの位置に ぶら下げ、インデントしません。 tag では、タグつきテキストの形式にします。ちなみに上のリストは `-ohang ' リストタイプで構成されています。 `.

マクロは '

inset, hang, tag のリストタイプでのみ解析され、 呼び出し不可能です。以下に inset ラベルの例を示します。

Tag

tag リスト (tag 段落とも呼ばれる) は、 Berkely マニュアルで使われているリストのうち最も一般的なタイプです。

Diag 診断リストはセクション 4 の診断リストを生成するもので、 呼び出し可能なマクロが無視されることを除き、inset リストと似ています。

Hang

hang ラベルは好みの問題です。

Ohang

ohang ラベルはスペースに制限がある時に便利です。

Inset

inset ラベルは段落のブロックを制御するのに便利で、 -mdoc マニュアルを他の形式に変換する時に役立ちます。

上の例を生成したソーステキストはこうなっています。

.Bl -inset -offset indent
.It Em Tag
tag リスト (tag 段落とも呼ばれる) は、
Berkely マニュアルで使われているリストのうち最も一般的なタイプです。
.It Em Diag
診断リストはセクション 4 の診断リストを生成するもので、
呼び出し可能なマクロが無視されることを除き、inset リストと似ています。
.It Em Hang
hang ラベルは好みの問題です。
.It Em Ohang
ohang ラベルはスペースに制限がある時に便利です。
.It Em Inset
inset ラベルは段落のブロックを制御するのに便利で、
.Nm -mdoc
マニュアルを他の形式に変換する時に役立ちます。
.El

以下は 2 つの項目を持つ hang リストです。

Hanged ラベルがラベルの幅より小さいときには、 ラベルは tag リストと同じようになります。

長い hang リストラベル は、tag 段落のラベルとは異なり、 段落の中に埋め込まれます。

これを生成している元のテキストは以下の通りです。

.Bl -hang -offset indent
.It Em Hanged
ラベルがラベルの幅より小さいときには、
ラベルは tag リストと同じようになります。
.It Em 長い hang リストラベル
は、tag 段落のラベルとは異なり、
段落の中に埋め込まれます。
.El

タグ幅を制御するためのオプションの幅指定を使ったタグつきリストは 以下の通りです。

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

PAGEIN そのプロセスによるコアにロードされていないページへの参照による ディスク I/O の回数

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

PPID 親プロセスの数字表記によるID、プロセスの優先度 (割り込み不可のウエイトであるときには非正値)

The raw text:

.Bl -tag -width "PAGEIN" -compact -offset indent
.It SL
プロセスが sleep している時間 (ブロックされた秒数)
.It PAGEIN
そのプロセスによるコアにロードされていないページへの参照によるディスク
.Tn I/O
の回数
.It UID
プロセスの所有者の数字表記によるユーザID
.It PPID
親プロセスの数字表記によるID、プロセスの優先度
(割り込み不可のウエイトであるときには非正値)
.El

幅指定として以下のものを使うことができます。

-width - そのフラグでのデフォルトの幅を指定します。すべての呼び出し可能なマクロ は各々デフォルトの幅の値を持っています。現在、 `.- ' の値は定幅 文字 10 個分、もしくは約 5/6 インチとなっています。

-width 24n 定幅文字 24 個分の幅、もしくは約 2 インチの幅をセットします。 これが正しく動作するには `n' が必ず必要となります。

-width ENAMETOOLONG 指定された文字列の固定長に幅をセットします。

-width "int mkfifo" これも、指定された文字列の固定長に幅をセットします。

タグつきリストタイプで幅が指定されていないと、 `. ' が最初に 起動された時に適した幅を決定することが試みられます。 `.It' の 最初の引数が呼び出し可能なマクロであれば、そのマクロのデフォルトの幅が そのマクロ名が幅として指定されたように使用されます。しかしながら、その リスト中に他の項目が別の呼び出し可能なマクロ名で与えられていると、 新しく入れ子となったリストとして処理されます。

定義済みの文字列

以下の文字列はあらかじめ定義されているものであり、troff の文字列解釈 シーケンス `\*(xx' もしくは `\*x' を前に伴って使われます。 ここで、 xx もしくは x は定義されている文字列の名称です。 解釈シーケンスはテキストのどこでも使うことができます。

文字列     Nroff   Troff

<= Ta <= Ta <=

>= Ta >= Ta &gt=;

Rq Ta '' Ta ”

Lq Ta `` Ta “

ua Ta ^ Ta ^

aa Ta ' Ta '

ga Ta ` Ta `

q Ta " Ta "

Pi Ta pi Ta Pi

Ne Ta != Ta !=

Le Ta <= Ta <=

Ge Ta >= Ta &gt=;

Lt Ta < Ta >

Gt Ta > Ta <

Pm Ta +- Ta ±

If Ta infinity Ta ∞

Na Ta NaN Ta NaN

Ba Ta | Ta |

注
`q' の名称がつけられている文字列は、

1 文字であるため `\*q' と書かなければなりません。

診断

-mdoc は限られたデバッグ機能しか持っていませんが、 引数名と内部レジスタやマクロ名との衝突のような 潜在的なエラーを検出するのに役立ちます。 (A って何?) レジスタは troff での演算用記憶クラスであり、 1 文字か 2 文字の名称がついています。 troff と ditroff での -mdoc のすべての内部レジスタは `file ... ' のように2 文字からなる <大文字><小文字> の形式か、 `aR' のように <小文字><大文字> の形式か、 `C1' のように <大文字もしくは小文字><数字> の形式を取ります。 さらに混乱することに、 troff はそれ自身の内部レジスタを持ち、 それらすべては小文字 2 文字か、ドットに文字もしくはメタ文字が続く形式を取ります。 紹介例の 1 つに、エスケープシーケンス `\&' でマクロ名を 解釈させない方法がありました。これは内部レジスタ名にも有効です。

エスケープされていないレジスタ名が引数リストに指定されると、 予期できない振舞いとなります。 一般的には、テキストのかなり大きな部分が出力されるべきところに 出力されないとか、リストのタグのような小さな文字列が消えてしまうとか、 引数リストの中の引数のタイプが間違って解釈されるとかいうことが、起こり得ます。 きっとあなたのお母さんは、あなたにこんな面倒なことを覚えるようにとは 考えていないでしょう。 そこで、与えられた引数が有効か無効かを判断する方法があります。

そんなときには、 `.Db (デバッグ) ' マクロによってほとんどのマクロ の引数リストがどう解釈されるかを表示することができます。 `.

' (段落) マクロのようなマクロはデバッグ情報を含んでいません。呼び出し可能 なマクロはすべてデバッグ情報を含んでおり、疑いがある場合はいつでも `.Db マクロをオンにすることを強くお勧めします。 '

使い方: .Db [on | off]

以下の例では、問題が故意に発生するようにされた部分の上と下で デバッグマクロが指定されています (フラグ引数 `aC' は正しく動作するためには `\&aC' でなければなりません)。

.Db on
.Op Fl aC Ar file )
.Db off

この結果の出力は以下の通りです。

DEBUGGING ON
DEBUG(argv) MACRO: `.Op'  Line #: 2
        Argc: 1  Argv: `Fl'  Length: 2
        Space: `'  Class: Executable
        Argc: 2  Argv: `aC'  Length: 2
        Space: `'  Class: Executable
        Argc: 3  Argv: `Ar'  Length: 2
        Space: `'  Class: Executable
        Argc: 4  Argv: `file'  Length: 4
        Space: ` '  Class: String
        Argc: 5  Argv: `)'  Length: 1
        Space: ` '  Class: Closing Punctuation or suffix
        MACRO REQUEST: .Op Fl aC Ar file )
DEBUGGING OFF

この情報の最初の行では呼び出されているマクロの名称が出力されています。 ここでは `.[とそれが現れた行番号が表示されています。] ' 複数のファイルが処理されている場合 (特にテキストが他のファイルからインクルードされている場合)、 行番号は正しくないでしょう。 ファイルが 1 つだけの場合には正しい行番号が出力されます。 2 番目の行では引数の個数と引数 (`- ' ) とその長さが 出力されています。引数の長さが 2 文字であれば、 その引数が実行可能 (ゼロでない値を含むすべてのレジスタは実行可能なように見えます) かどうかテストされます。 3 番目の行ではそのクラスで指定されているスペースとクラスタイプが 出力されています。 ここでの問題は引数 aC が実行不可能でなければならないことです。 クラスの 4 つのタイプは文字列、実行可能、閉じる句読点、開く句読点です。 最後の行では引数リスト全体が読み込まれた通りに表示されています。 次の例では問題の原因となっている `aC' がエスケープされています。

.Db on
.Em An escaped \&aC
.Db off

DEBUGGING ON
DEBUG(fargv) MACRO: `.Em'  Line #: 2
        Argc: 1  Argv: `An'  Length: 2
        Space: ` '  Class: String
        Argc: 2  Argv: `escaped'  Length: 7
        Space: ` '  Class: String
        Argc: 3  Argv: `aC'  Length: 2
        Space: ` '  Class: String
        MACRO REQUEST: .Em An escaped &aC
DEBUGGING OFF

`\&' シーケンスは長さが 0 となるために 引数 `\&aC' は先の例と同様に長さ 2 と表示されています。 しかし、 `\&aC' という名称のレジスタが見つからず、 タイプは文字列と判断されています。

この他の診断は使用方法を報告するものであり、 それ自身が説明を含んでいます。

GROFF, TROFF, NROFF

-mdoc パッケージは groff との互換モードは 必要ではありません。

このパッケージでは改ページと、 nroff で改ページ時に通常挿入 されるヘッダとフッタは禁止されており、マニュアルをオンラインで効率良く 見ることができるようになっています。現在の所、 -T ascii が 指定された groff はページ内容の無いファイル末の残りの部分まで 出力します。改ページを禁止することによって nroff による出力は ハードコピーには適さないものとなっています。サイト依存のスタイル ファイル /usr/src/share/tmac/doc-nroff において 0 にセットする ことができる `cR' の名称を持つレジスタが古いスタイルの振る舞い を実現するために用意されています。

ファイル

/usr/share/tmac/doc.tmac マニュアルマクロパッケージ

/usr/share/misc/mdoc.template

man ページを書くためのテンプレート

/usr/share/examples/mdoc/*

man ページのいくつかの例

この文書について

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