UNIX マニュアルページ全体を通して、マニュアルのエントリは単純に マニュアルページ (a man page) とみなされます。 これは実際のページ数と関係ありませんし、性差別をする意図もありません。
一般的に GNU troff(1) マクロは取り得る引数の数に制限はありません (9 つ以上の 引数を扱うことのできない他のバージョンの troff とは違います)。 限られた場合ではありますが、引数を次の行に続けたり、拡張したり することができます (後述の Sx 拡張引数 のセクションを参照)。 ほとんどすべてのマクロで引用符に囲まれた引数を扱うことができます (後述の Sx 引数に空白文字を指定する のセクションを参照)。
-mdoc での一般テキスト領域とマニュアル領域のほとんどのマクロは、 呼び出し可能なマクロ名を決定するためにその引数のリストが 構文解析 されるという点で特別なものです。 これはつまり、一般テキスト領域またはマニュアル領域のマクロ名に一致し (かつ、呼び出し可能であると定義された) 引数リスト中の引数は、 処理される時に実行されるか、もしくは呼び出されるということです。 この場合、引数がマクロの名前であっても `.' (ドット) で前置されません。 このようにしてたくさんのマクロを入れ子にすることができます。 例えばオプションマクロ `.[はフラグマクロおよび引数マクロ] ' `- ' と `file ... ' を 呼び出し て、オプションのフラグを引数とともに指定することができます:
文字列がマクロ名と解釈されないようにするには、 その文字列の前にエスケープシーケンス `\&' を指定します。
ここで文字列 `- ' と `file ... ' はマクロとして解釈されていません。 このドキュメントを通じて、 呼び出し可能な引数を調べるために引数リストが構文解析されるマクロは 構文解析される マクロとして参照し、 引数リストから呼び出されることができるマクロは 呼び出し可能 なマクロとして参照します。 -mdoc のマクロはほとんどすべてが構文解析されるのですから、これは技術的には 適当でない 表現ですが、常にマクロを「呼び出し可能である」とか「他のマクロを 呼び出すことができる」と表現するのは面倒なことであるため、 「構文解析される」という用語を使います。
以降、この区別が必要な場合、行頭 (でドットで開始する) -mdoc マクロを コマンド と呼びます。
空白を含む引数を指定するには 2 通りの方法があります。 1 つは、空白を含む文字列を渡すのに、固定の空白、 つまりパディングされない空白文字 `\' を使う方法です。 すなわち、空白の前にエスケープ文字 `\' を指定します。 この方法はどのマクロでも使うことができますが、1 行が長くなり過ぎた テキストを調整するときの邪魔になるという副作用があります。 troff では、固定の空白は他の印刷可能な文字と同様に扱われ、通常期待されるように その箇所で文字列を空白や改行で分けることは行われなくなります。 この方法は文字列が行の境界にまたがることが好ましくない場合に有用です。 代替案としては、 パディング可能 (すなわち伸長可能) で分割不可能な空白 `\~' を使うことがあります (これは、 GNU troff(1) 拡張です)。 2 つ目の方法は、文字列をダブルクォートで括ることです。
例えば、次のようにします:
もし、最初の例の空白の前もしくは次の例のダブルクォートの前の `\' が省略されていた場合には `.Fn は引数が ' 3 つであるとみなし、その結果は
Fn fetch char *str
先頭に空白を置くと行分割が生じ、そのまま出力されてしまいます。 可能ならばこうなることを避けてください。 同様に、通常のテキスト行において単語間に 2 つ以上の空白文字を 使用しないでください。 これは、他のテキストフォーマッタとは対照的です。 空白文字を 2 つ以上置いても 1 つの空白文字に置き換わり ません 。
引数として `q]' を直接渡すことはできません。 代わりに `\*[q]' (あるいは `\*q' ) を使用してください。
デフォルトでは、 troff(1) は文を終了させる句読点の後に空白文字を 2 つ挿入します。 つまり、 `)' あるいは `'' などの文字はそのまま扱われ、文の終了には影響を与えません。 この動作を変更するには、 ドットの前あるいは後に `\&' を挿入してください。
The .Ql . character. .Pp The .Ql \&. character. .Pp .No test . test .Pp .No test. test
は、
The `.' character.The `.' character.
test test
test. test
となります。
1 行目および 3 行目にみられるように、 -mdoc はマクロ引数の中では句読点を特別に扱います。 これについては、後述の Sx 一般的な構文 の節で述べます。 同様の方法で、幅 0 の空白を続けることで、 省略形の後に続いたピリオドを保護しなくてはなりません。 例えば `e.g.\&' のようにします。
マニュアルページのソースファイル中のコメントは、 独立した行では `.\' 、何らかの入力があった後では `\' を、あるいはどのような場所でも使いたい場合は `\#' を使うことができます (後者は GNU troff(1) 拡張です)。 このような行の残りの部分は無視されます。
.\" 以下のコマンドはすべてのマニュアルページで必要な項目です。 .Dd 月 日, 年 .Os [オペレーティングシステム] [バージョン/リリース] .Dt ドキュメントタイトル [セクション番号] [アーキテクチャ/ボリューム] .Sh NAME .Nm 名称 .Nd 名称についての 1 行での説明 .\" 次のコマンドはセクション 2, 3 でのみ必要なものです。 .\" .Sh LIBRARY .Sh SYNOPSIS .Sh DESCRIPTION .\" 以下のコマンドについては、必要に応じてコメントをはずして使用して .\" ください。 .\" .Sh IMPLEMENTATION NOTES .\" この次のコマンドはセクション 2, 3, 9 でのみ必要な、関数の .\" 戻り値です。 .\" .Sh RETURN VALUES .\" 次のコマンドはセクション 1, 6, 7, 8, 9 でのみ必要なものです。 .\" .Sh ENVIRONMENT .\" .Sh FILES .\" .Sh EXAMPLES .\" 次のコマンドはセクション 1, 6, 7, 8, 9 でのみ必要なものです。 .\" ((シェルへの)コマンドの戻り値と .\" fprintf/stderr タイプの診断です) .\" .Sh DIAGNOSTICS .\" .Sh COMPATIBILITY .\" 次のコマンドはセクション 2, 3, 9 でのみ必要な、 .\" エラーハンドリングとシグナルハンドリングです。 .\" .Sh ERRORS .\" .Sh SEE ALSO .\" .Sh STANDARDS .\" .Sh HISTORY .\" .Sh AUTHORS .\" .Sh BUGS
このテンプレートにおける最初のコマンドはマクロ `., ' `., ' および `. ' であり、それぞれドキュメントの日付、 マニュアルページもしくは題材となっているソースの開発や変更の 対象となったオペレーティングシステム、そして マニュアルページのタイトルを属するマニュアルのセクション番号と ともに ( 大文字で 指定したもの、となっています。 これらのコマンドはそのページを識別するものであり、後述の Sx タイトルマクロ で解説されます。
例:
とくに明示しない限り、すべてのマクロは 構文解析され、呼び出し可能なものです。
マクロの効果が持続するのは、 次のネストしたマクロまでであることに注意してください。 例えば `.foo '
大部分のマクロはデフォルトの幅の値を持っており、これを `.
' および `. ' マクロ用にラベル width ( -width あるいは offset ( -offset を指定するのに使用することができます。 -mdoc パッケージのローカルな変更に依存することのないように、 このとても曖昧な機能は使わないことを推奨します。
operating-system] では、次のセクションが定義されています:
ボリューム名は任意であるか、もしくは次のものを 取ることができます:
互換性を保つため、 `IND' の代わりに `MMI' を使用することができ、 `LOCAL' の代わりに `LOC' を使用できます。 先の表の値は、新しいボリューム名を指定します。 第 3 パラメータがコンピュータアーキテクチャを表すキーワードで ある場合、その値は第 2 パラメータで指定したボリューム名の 前に追加されます。 デフォルトでは次のアーキテクチャに関するキーワードが定義されています: # we use `No' to avoid hyphenation
alpha , acorn26 , acorn32 , algor , amd64 , amiga , arc , arm26 arm32 , atari , bebox , cats , cesfic , cobalt , dreamcast , evbarm evbmips , evbppc , evbsh3 , hp300 , hp700 , hpcmips , i386 , luna68k m68k , mac68k , macppc , mips , mmeye , mvme68k , mvmeppc , netwinder news68k , newsmips , next68k , ofppc , pc532 , pmax , pmppc , powerpc prep , sandpoint , sgimips , sh3 , shark , sparc , sparc64 , sun3 tahoe , vax , x68k , x86_64
セクション番号が 1 から 9 の範囲の数値ではなく、 また前述のキーワードでない場合、 第 3 パラメータがそのままボリューム名として使用されます。
次の例では、マニュアルページのヘッダの左側 (これは右側と同じものです) と 中央に書かれる文字列を示しています。 `\&' が数値 7 を正当な数値として解釈されないようにしている点に注意してください。
ローカルな追加項目や OS に特化した追加項目が、ファイル mdoc.local にあるかもしれません。 このファイル中で `volume-ds-XXX' (前者のタイプについて) および `volume-as-XXX' (後者のタイプについて) という名前の文字列を検索してください。 ここで `XXX' は `. ' マクロで使用されるキーワードを表しています。
このマクロは呼び出し不可能であり、構文解析もされません。
ATT に関しては、判別できない第 2 パラメータがある時には それを文字列 UNIX に置き換えます。 事前に定義されているその他の頭字語 (略称) に ついては、そのようなパラメータは無視され、警告メッセージが 出力されます。 認識できない引数は、ページフッタ中に記述された通りに 表示されます。 例えば、典型的なフッタは次のようになるでしょう:
.BSD 4.3
は `4.3~Berkeley' Distribution となります。 また、ローカルで作られたセットの例では、
.CS Department
は `CS~Department' となります。
`.マクロがない場合、ページの左下隅は見苦しくなってしまうでしょう。 '
このマクロは呼び出し不可能であり、構文解析もされません。
.January 25, 2001
それ以外の場合は現在の日付が使用され、パラメータは無視されます。
このマクロは呼び出し不可能であり、構文解析もされません。
最初のケースでは、 troff(1) マクロはそれ自身、一種のコマンドとなっています。 troff コマンドは一般的に以下のような形式をとります。
.Xx argument1 argument2 ...
`.Xx はマクロコマンドを示しており、それに続くものは ' すべて処理されるべき引数として処理されます。 2 番目のケースでは、コンテントマクロを使用する UNIX コマンドの記述がもう少し含まれます。 典型的な Sx SYNOPSIS コマンド行はこのように表示されます。
filter [-flag ] Ao Ar infile Ac Ao Ar outfile Ac
ここで filter はコマンド名であり、角括弧で囲まれた文字列 -flag は フラグ 引数で、これは角括弧で囲むことによってオプションであることを 示しています。 -mdoc の用語では、 Ao Ar infile Ac および Ao Ar outfile Ac は メタ引数 と称されています。 この例では、ユーザは山括弧 (<>) の中で与えられたメタ引数を 実際のファイル名に置き換えなくてはなりません。 このドキュメントでは、メタ引数は -mdoc コマンドを記述するのに使用していることに注意してください。 多くのマニュアルページでは、メタ変数はわざわざ山括弧を使って 書かれていません。 上の例を整形したマクロは以下のものです。
.Nm filter .Op Fl flag .Ao Ar infile Ac Ao Ar outfile Ac
3 番目のケースでは、コマンドの説明や構文に上記の例の両方が使われ、 さらに細かい記述が追加されるでしょう。 上の例での引数 Ao Ar infile Ac および Ao Ar outfile Ac は オペランド もしくは ファイル引数 として参照されます。 コマンド行の引数のリストはかなり長くなる場合もあります。
ここではコマンド make について記述しており、 makefile をフラグ -f の引数としています。 またオプションのファイルオペランドである target についても言及しています。 言葉での説明では、こういった詳細な記述が混乱を防いでくれますが、 -mdoc パッケージにはフラグ への 引数のためのマクロがありません。 その代わりに target のようなオペランドやファイル引数に使われる引数マクロ `file ... ' が variable のようなフラグへの引数と同様に使われます。 この make コマンド行は次の指定により生成されています。
.Nm make .Op Fl eiknqrstv .Op Fl D Ar variable .Op Fl d Ar flags .Op Fl f Ar makefile .Op Fl I Ar directory .Op Fl j Ar max_jobs .Op Ar variable Ns = Ns Ar value .Bk .Op Ar target ... .Ek
マクロ `.および ' `.は ' Sx キープ セクションにおいて解説されています。
.sptr, ptr),
その結果は以下のようになります。
sptr, ptr),
ここでは句読点は認識されず、すべての出力は `.file ... ' で使用されるフォントで行われています。 句読点が空白文字で区切られている場合、
.sptr , ptr ) ,
結果は以下のようになります。
sptr , ptr
今度は句読点が認識され、出力はデフォルトのフォントで行われ 引数文字列とは区別されています。 句読点文字の特別な意味を取り除くには、 `\&' でエスケープしてください。
-mdoc は次の句読点文字を認識します。
troff はマクロ言語としての限界から、以下のような、数学、論理学、引用符の 集合のメンバを含んだ文字列を表現するのは困難です。
{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
問題なのは、文字によって示唆されている操作もしくは評価が、 実行されるべきであると troff が仮定する場合があることです。 これらの文字が予期しない形で評価されないようにするには、 `\&' でこれらをエスケープしてください。 最初のコンテントマクロは、以下の `.において、その典型的な構文が示されています。 '
使い方: .Ao アドレス Ac ...
使い方: .An Ao 作者名 Ac ...
デフォルトの文字幅は 12n です。
Sx AUTHORS セクションでは、 `.An リクエストは改行を引き起こし、新しい名前がそれぞれの行に表示されます。 ' この動作が望ましくない場合、
.An -nosplit
を呼び出すことで無効にできます。 それぞれの行に表示させる動作に戻したい場合は、
.An -split
使い方: .[Ao 引数 Ac ...]
使い方: .Ao 引数 Ac ...
Sx SYNOPSIS セクションでは `.リクエストはその引数が表示される前後で改行を入れます。 '
使い方: .Ao 定義済みの変数 Ac ...
使い方: .Er Ao errno のタイプ Ac ...
使い方: .Ao 引数 Ac ...
使い方: .-Ao 引数 Ac ...
引数なしで `.- ' マクロを指定すると、標準入力/標準出力を意味するダッシュとなります。 `.- ' マクロにダッシュを 1 つ与えると、2 つのダッシュとなることに 注意して下さい。
使い方: .Fd Ao 引数 Ac ...
Sx SYNOPSIS セクションでは、 関数がすでに示されており、改行がまだされていない場合には `.Fd リクエストは改行を入れます。 ' これによって前の関数呼び出しと次の関数の宣言の間に 最適な行間が設定されます。
`.In マクロは、 ' Sx SYNOPSIS セクションで使用すると、 #include 文を表現するものであり、以上の例を短く記述したものです。 このマクロは C プログラム中でインクルードされる C ヘッダファイルを指定します。 このマクロも改行を挿入します。
Sx SYNOPSIS セクション以外で使用すると、 山括弧で括られたヘッダファイルを表現します。
使い方: .In Ao ヘッダファイル Ac
使い方: .Ft Ao 型 Ac ...
使い方: .Fn Ao 関数 Ac [Ao パラメータ Ac ...]
他のマクロを呼び出すと `.Fn 呼び出しの終了を意味することに注意してください ' (閉じ括弧がその箇所に挿入されます)。
多くのパラメータをとる関数 (これは滅多にないことですが) では、 `.Fo マクロ ' (関数マクロの開始) と `.Fc マクロ ' (関数マクロの終了) を `.Fa (関数の引数) ' と共に使って、この制限を回避することができます。
使用例:
.Ft int .Fo 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
生成結果:
Ft int Fo 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
Sx SYNOPSIS セクションでは、関数は常に行の先頭から開始されます。 Sx SYNOPSIS セクションにおいて複数の関数が示されており、関数の型が 示されない場合、改行が挿入され、現在の関数名とその前の 関数名の間に最適な改行量が設定されます。
`.Fn および ' `.Fo のデフォルト幅の値はそれぞれ ' 12n と 16n です。
使い方: .Fa Ao 関数の引数 Ac ...
使い方: .Rv [-std [Ao 関数 Ac ... ] ]
例えば、 `.Rv -std ' atexit は次のテキストを生成します。 # a small hack to suppress a warning message Rv -std atexit
-std オプションはセクション 2 と 3 のマニュアルページでのみ有効です。 現在のところ、このマクロは -std フラグなしで使用しても何も起こりません。
使い方: .Ex [-std [Ao ユーティリティ Ac ... ] ]
例えば `.Ex -std ' cat は次のテキストを生成します。 # a small hack to suppress a warning message Ex -std cat
-std オプションはセクション 1 と 6 と 8 のマニュアルページでのみ有効です。 現在のところ、このマクロは -std フラグなしで使用しても何も起こりません。
使い方: .Ao 引数 Ac ...
使い方: .Lb Ao 引数 Ac ...
`.Lb マクロに対して使用可能な引数と結果は次の通りです: '
ローカルな追加項目や OS 特有の追加項目が、ファイル mdoc.local にあるかもしれません。 `str-Lb-XXX' という名前の文字列を検索してください。 ここで `XXX' は `.Lb マクロとともに使用されるキーワードを示しています。 '
Sx ライブラリ のセクションでは、 `.Lb コマンドは、引数の表示の前後でラインブレークを引き起こします。 '
使い方: .Ao 引数 Ac ...
使い方: .[Ao 引数 Ac ...]
使い方: .[[Ao オプション Ac ...] ]
これは、 `.[マクロと ' `.] ' マクロを使った典型的な例です:
.Oo .Op Fl k Ar kilobytes .Op Fl i Ar interval .Op Fl c Ar count .Oc
出力結果:
[[-k kilobytes ] [-i interval ] [-c count ] ]
`.[マクロおよび] ' `.[マクロのデフォルト幅はそれぞれ ' 14n と 10n です。
使い方: .[Ao パス名 Ac ...]
使い方: .St Ao 短縮名称 Ac ...
使用可能な ``短縮名称/正式名称'' の組は次の通りです:
ANSI/ISO C
POSIX パート 1: System API
POSIX パート 2: シェルとユーティリティ
X/Open
その他
使い方: .Vt Ao 型 Ac ...
使い方: .Ao 変数 Ac ...
使い方: .Aoマニュアルページの名称AcOoAoセクションAcOc...
使い方: .AT&T System [Ao バージョン Ac ...]
Ao バージョン Ac には次の値をとることができます:
32v, v1, v2, v3, v4, v5, v6, v7, V, V.1, V.2, V.3, V.4
"使い方: .Bx" Bro -alpha | -beta | -devel Brc ...
" .Bx" [Ao バージョン Ac [Ao リリース Ac ...] ]
Ao バージョン Ac が文字列 `BSD の前につきます。 ' Ao リリース Ac には次の値をとることができます:
Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
使い方: .Nx [Ao バージョン Ac ...]
Ao バージョン Ac にとり得る値については前述の Sx タイトルマクロ セクションの `.コマンドの説明を参照してください。 '
使い方: .Fx [Ao バージョン Ac ...]
Ao バージョン Ac にとり得る値については前述の Sx タイトルマクロ セクションの `.コマンドの説明を参照してください。 '
使い方: .Ox [Ao バージョン Ac ...]
使い方: .Bsx [Ao バージョン Ac ...]
使い方: .UNIX
使い方: .Ao 引数 Ac ...
`.Bf は次の文法をもっています: '
.Bf Ao フォントモード AcAo フォントモード Ac は次の 3 種類のうちのいずれかでなくてはなりません。
いずれのマクロも呼び出し不可能であり、構文解析もされません。
# XXX
クォート Ta 開始 Ta 終了 Ta 機能 Ta 結果
.Aq Ta .Ao Ta .Ac Ta 山括弧による囲い Ta Ao string Ac .Bq Ta .Bo Ta .Bc Ta 角括弧による囲い Ta Bo string Bc .Brq Ta .Bro Ta .Brc Ta 中括弧による囲い Ta Bro string Brc
.``Ta .Do Ta .Dc Ta 2 重引用符 Ta Do string Dc .Eq Ta .Eo Ta .Ec Ta 囲い文字列 (XX による) Ta XXstringXX
''
.(Ta .Po Ta .Pc Ta 括弧による囲い Ta Po string Pc .`Ta Ta Ta クォートされたリテラル
'
)
Ta So string Sc もしくは Li string
.Qq Ta .Qo Ta .Qc Ta まっすぐな 2 重引用符 Ta Qo string Qc .`Ta .So Ta .Sc Ta 1 重引用符 Ta So string Sc
'
`q' および `o' で終わるマクロはすべてデフォルト幅が 12n です。
デフォルト幅は 16n です。
デフォルト幅は 12n です。
`.マクロ ' (後述参照) は同じようにサフィックスに働きます。
クォートの例:
囲いマクロの入れ子についての良い例については、 オプションマクロ `.[を参照してください。] ' このマクロは上でリストされているような囲いマクロと同じベースの上に 作られています。 `. ' と `. ' 拡張引数リストマクロについては後で述べます。
使い方: .Ao 引数 Ac ...
"使い方:" ... Ao 引数 Ac [Ao 引数 Ac ...]
" " .Ao 引数 Ac ...
注: `.マクロは他のマクロ名が続かなければ、スペースを除去したあとに ' `.マクロを常に起動します。 ' コマンドとして使用される場合 (つまり、 `使い方' の行での 2 番目の形式です)、 `.マクロは ' `.と同一です。 '
使い方: .Sx Ao セクションの参照 Ac ...
使い方: .Ao 記号 Ac ...
使い方: .Ao 数学記号 Ac ...
`%' で始まるマクロは呼び出し不可能ですが、 通常の方法で複数の引数をとることができます。 パラメータとしては `.マクロのみ扱います。 ' その他のマクロを使うと 奇妙な出力が得られてしまいます。 `.%B' および `.%T' を `.Rs/.
使用例:
.Rs .%A "Matthew Bar" .%A "John Foo" .%T "Implementation Notes on foobar(1)" .%R "Technical Report ABC-DE-12-345" .%Q "Drofnats College, Nowhere" .%D "April 1991" .Re
出力結果
- "Matthew Bar" "John Foo" "Implementation Notes on foobar(1)" "Technical Report ABC-DE-12-345" "Drofnats College, Nowhere" "April 1991"
使い方: .Ao シンボル Ac ...
次は、スペーシングをオフにするために 空白モードマクロを使った `. ' の使用例です。
.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 Oo .Ar operator variable ... .Oc Xc
結果は以下の通りです。
- .ifndef [! variable [operator variable ... ]
- ]
デフォルト幅は 8n です。
`. - は全ての引数の頭に ' `-' , を印字します。 Li ".Sh LIBRARY" このセクションは、セクション 2 および 3 の関数呼び出しの ためにあります。 このセクションには、 `.Lb マクロ呼び出し ' 1 つのみが含まれている必要があります。 Sx ライブラリ名 を参照してください。 Li ".Sh SYNOPSIS" Sx SYNOPSIS セクションはそのマニュアルページのサブジェクトとなっている項目の 典型的な使用法を説明します。 `. ' `., ' あるいは `.Fn です ' (他には `.Fo , ' `.Fc , ' `.Fd , ' `.Ft のマクロも必要な場合があります)。 ' 関数名マクロ `.Fn はセクション ' 2 と 3 のマニュアルページにおいて必須のもので、 コマンドと一般名称マクロ `. ' はセクション 1, 5, 6, 7, 8 で必須の項目です。 セクション 4 のマニュアルでは `. ' か `.Fd 、もしくは設定デバイス使用法マクロ ' `.が必要です。 ' その他のいくつかのマクロが次に示すような書式行を生成するために 必要なことがあります:
cat [-benstuv ] [- ] file ...
次のマクロが使われています:
".cat
".[-benstuv ]
".[Fl]
.file ...Li ".Sh DESCRIPTION" ほとんどの場合、 Sx DESCRIPTION セクションでの最初のテキストはそのコマンド、関数もしくは ファイルについての短い段落で、オプションの構文リストと それぞれの説明がそれに続きます。 そのようなリストを作成するには `.
' (リスト開始マクロ)、 `.
' (リスト終了マクロ) を使用します (後述の Sx リストとカラム セクションを参照)。 Li ".Sh IMPLEMENTATION NOTES" 特定の実装に関する情報はここに置く必要があります。 Li ".Sh RETURN VALUES" セクション 2, 3, 9 の関数の戻り値はここに来る必要があります。 `.Rv を使用して、セクション ' 2 および 3 のライブラリ関数の Sx RETURN VALUES セクションを生成することができます。 Sx 戻り値 の項を参照してください。
クロスリファレンスはセクション番号順、同一セクションにあるものは アルファベット順に並べ、コンマで区切ることを推奨します。 以下に例を示します:
ls(1), ps(1), group(5), passwd(5) Li ".Sh STANDARDS" コマンドやライブラリ関数やファイルが、 St -p1003.2 や St -ansiC のような特定の実装によるものであれば、ここで記述します。 もしコマンドがどの規格にも基づいていなければ、その歴史は Sx HISTORY のセクションで説明されなければなりません。 Li ".Sh HISTORY" 特定の規格に基づいていないコマンドは、 このセクションでその歴史の概要を説明する必要があります。 Li ".Sh AUTHORS" クレジットはここに置く必要があります。 人物名を指定するには `.An マクロを使用する必要があります。 ' Li ".Sh BUGS" あきらかな問題はここで記述します。
.Sh "ページ構造領域"
' 段落コマンドは必要な場合に行スペースを指定するために使われます。 このマクロは `.
' マクロや `. ' マクロの前では必要ありません (いずれのマクロも -compact フラグが指定されていなければ垂直方向の距離を宣言します)。
このマクロは呼び出し不可能であり、構文解析もされません。 そして引数をとりません。 別名は `.Lp です。 '
いずれのマクロも呼び出し不可能であり、構文解析もされません。
キープマクロについてはもっと作業をする必要があります。 特に -line オプションは追加する必要があるでしょう。
これは次の指定で生成されたものです: .D1 -ldghfstru
マクロの例は本ファイル中にわたって使われています。' これによって 1 行のテキストのインデント (表示) が可能になります。 デフォルトフォントは固定幅 (リテラル) に設定されます。 `.
は構文解析されますが、呼び出し不可能です。'
% ls -ldg /usr/local/bin
これは、次の指定で生成されたものです: . % ls -ldg /usr/local/bin
マクロでも使われていますので、この' 2 つのディスプレイと 行が揃うことが保証されています。 インデント値は通常 6n つまり約 2/3 インチ (固定幅文字 6 つ分) です。
Ao 文字列 Ac がそれ以外で正しい数値表現をしている場合 ( `u ' 以外のスケール指示子を伴う 、 インデント用にその値を使用します。 スケール指示子のなかで最も役に立つものは `m' および `n' です。 これらはいわゆる と En square を指定します。 これらはそれぞれ、現在のフォントでの文字 `m' および文字 `n' の幅とほぼ同じです ( nroff の出力については、 どちらのスケール指示子でも同じ値が得られます )。 Ao 文字列 Ac が数値表現をしていない場合、文字列は -mdoc マクロ名であるかどうか検査され、このマクロに関連する デフォルトのオフセット値が使われます。 最終的にすべてのテストが失敗した場合 the width of Ao 文字列 Ac の幅 (固定幅フォントでのタイプセット) がオフセットと見なされます。
' で開始できるリストには何種類かあります。 リスト中の項目は項目マクロ `.
' マクロで終了しなければなりません。 リストはリスト自身やディスプレイの中で入れ子にすることができます。 リスト中でカラムを使ったり、カラムの中でリストを使ったりすることに ついては検証されていません。
さらに、タグ幅、リストのオフセット、コンパクトの度合 (項目間の空白行が許されているかどうか) のような リストの属性をいくつか指定することができます。 本ドキュメントのほとんどはタグ ( -tag スタイルリストで整形されています。
このマクロは次の文法規則を持っています:
次に、このリストタイプの詳細な解説を行います。
.Bl -bullet -offset indent -compact .It 1 つ目のビュレットはここにきます。 .It 2 つ目のビュレットはここにきます。 .El
生成結果は次の通りです:
.Bl -dash -offset indent -compact .It 1 つ目のダッシュはここにきます。 .It 2 つ目のダッシュはここにきます。 .El
生成結果は次の通りです:
.Bl -enum -offset indent -compact .It 1 つ目の項目はここにきます。 .It 2 つ目の項目はここにきます。 .El
生成結果は次の通りです:
箇条書きリストを入れ子にしたい場合、 -nested フラグを使用してください (第 2 レベルのリストが開始されます):
.Bl -enum -offset indent -compact .It 1 つ目の項目はここにきます。 .Bl -enum -nested -compact .It 2 つ目の項目はここにきます。 .It 3 つ目の項目はここにきます。 .It .El .It 4 つ目の項目はここにきます。 .El
生成結果は次の通りです:
.Bl -item -offset indent .It 1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 .It 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 .El
生成結果は次の通りです:
元のテキストは次の通りです:
.Bl -tag -width "PPID" -compact -offset indent .It SL プロセスが sleep している時間 (ブロックされた秒数) .It PAGEIN そのプロセスによって、まだメモリにロードされていないページ への参照が起こることにより生じたディスク .Tn I/O の回数 .It UID 数値表記によるプロセス所有者のユーザ ID .It PPID 数値表記による親プロセスの ID、プロセスの優先度 (割り込み不可の待機状態のときには、正でない値になる) .El
使用例:
.Bl -diag .It ここで Sy を使うことはできません。 このメッセージはすべて出力されます。 .El
生成結果
以上の文章を生成した、整形前のテキストは 次の通りです:
.Bl -hang -offset indent .It Em Hanged ラベル幅よりもラベルが小さい場合には ぶら下げられたラベルはタグつきリストと同じようにみえます。 .It Em Longer Hanged list labels ラベル幅より長いぶら下がりリストのラベルは、 タグつき段落ラベルとは違い、段落に溶け込みます。 .El
元のテキストは次の通りです:
.Bl -ohang -offset indent .It Sy SL プロセスが sleep している時間 (ブロックされた秒数) .It Sy PAGEIN そのプロセスによって、まだメモリにロードされていないページ への参照が起こることで生じたディスク .Tn I/O の回数 .It Sy UID 数値表記によるプロセス所有者のユーザ ID .It Sy PPID 数値表記による親プロセスの ID、プロセスの優先度 (割り込み不可の待機状態のときには、正でない値になる) .El
上の例を生成したソーステキストはこうなっています:
.Bl -inset -offset indent .It Em tag タグリスト (タグ段落とも呼びます) は バークレーのマニュアルで使われている最も一般的な 種類のリストです。 後で述べるように、 .Fl width 属性を使用してください。 .It Em diag 診断リストはセクション 4 の診断リストを生成し、 呼び出し可能なマクロを無視するという点を除けば inset リストと似ています。 .It Em hang ぶら下がりラベルは気分の問題です。 .It Em ohang オーバハングラベルは空白に制限がある場合には良いです。 .It Em inset inset ラベルは段落ブロックを制御するのに便利で、 .Nm -mdoc マニュアルを別のフォーマットに変換するのに有用です。 .El
`.
次の表、
は次のようにして生成されています:
.Bl -column -offset indent ".Sy 文字列" ".Sy nroff" ".Sy troff" .It Sy 文字列 Ta Sy nroff Ta Sy troff .It Li <= Ta <= Ta \*(<= .It Li >= Ta >= Ta \*(>= .El
その他のキーワード:
使用例:
.Bl -tag -width ".Fl test Ao Ar 文字列 Ac" .It Fl test Ao Ar 文字列 Ac これは、 .Fl width フラグをタグリストと一緒に使うとどのように 働くかを見るためのもっと長い文です。 .El
生成結果:
Ao 文字列 Ac が解釈される前に現在の -mdoc の状態が保存されることに注意してください。 文字列が解釈された後ですべての変数が再度復元されます。 しかし、ボックス (囲いに使用される) は GNU troff(1) では保存されません。 結果としては、醜いエラーを防ぐためには引数は常に 平衡がとれて いなくてはなりません。 例えば、本当に開き山括弧だけが必要である場合には `.Ao 文字列 ' と書いてはだめで、代わりに `.Ao 文字列 ' Xc と書かなくてはなりません。
そうでない場合、 Aq Ar 文字列 が正当な数値表現である場合 `( u ' 以外のスケール指示子を伴う 、 インデント用にその値を使用します。 最も有用なスケール指示子は `m' と `n' です。 これらはいわゆる および En square を指定します。 これらはそれぞれ、現在のフォントでの文字 `m' および文字 `n' の幅とほぼ同じです (nroff の出力については、 どちらのスケール指示子でも同じ値が得られます)。 Aq Ar 文字列 が数値表現をしていない場合、文字列は -mdoc マクロ名であるかどうか検査され、このマクロに関連する デフォルトのオフセット値が使われます。 最終的にすべてのテストが失敗した場合 Aq Ar 文字列 の幅 (固定幅フォントでのタイプセット) がオフセットと見なされます。
タグリストタイプ用に幅が指定されていない場合、 `.
または' `. ' で使われる値と似ています) が使われます。 Aq Ar 文字列 が正当な数値表現である場合 ( `u ' 以外のスケール指示子を伴う 、 その値をインデントに使用します。 最も有用なスケール指示子は `m' と `n' であり、これらはいわゆる および En square です。 これらはそれぞれ、それぞれ現在のフォントでの `m' と `n' の幅とほぼ同じです (nroff の出力については、 どちらのスケール指示子も同じ値をとります)。 Ao 文字列 Ac が数値表現でない場合、その文字列が -mdoc のマクロ名であるかどうか検査され、このマクロに関連する デフォルトのオフセット値が使われます。 最終的にすべてのテストが失敗した場合、 Aq Ar 文字列 の幅 (固定幅フォントでのタイプセット) がオフセットとして とられます。
is currently in beta test.
を表示します。
このマクロは呼び出し不可能であり、構文解析もされません。 また引数もとりません。
使い方: .Ao 関数の戻り値 Ac ...
このマクロは使わないでください。 このマクロは戻り値 (通常は数字 1 個) の直前での 改行を許してしまいます。 印刷時の振る舞いとしては悪いことです。 直前の単語と戻り値とを結合させるには `\~' を使用してください。
使い方: .Hf Ao ファイル Acこのマクロは呼び出し不可能であり、構文解析もされません。
デフォルト幅は 6n です。
使い方: .
空白モードが off の場合、マクロ引数の間に空白は 挿入されません。 引数なしで呼ばれた場合 (あるいは次の引数が `on' でも `off' でもない場合) `. ' マクロは空白モードに入ります。
Ud
を表示します。
このマクロは呼び出し不可能であり、構文解析もされません。 また引数もとりません。
カラムの名前 nroff と troff は少々誤解を招くものです。 nroff は ASCII 文字を表示しますが、 troff では利用可能なもののうち一番良いグリフ形式を 表示します。 例えば、Unicode を使用可能にした TTY デバイスはすべての文字列に対して適切なグリフ表現を 持っていますが、それに対して Latin1 に対して機能を強化した TTY デバイスはプラスマイナス記号しか持っていません。
文字を 2 つ含んだ文字列名は `\*(xx' として表記できます。 文字を 1 文字だけ含んだ文字列名は `\*x' と表記できます。 どのような長さの文字列名に対しても、一般的な文法は `\*[xxx]' となります ( これは GNU troff(1) 拡張です)。 # #===================================================================== #
唯一残ったデバッグ用マクロは `.Rd であり、これはすべてのグローバルレジスタならびに文字列の ' レジスタダンプを出力するものです。 通常のユーザが使う必要は決してないでしょう。
groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt
両面印刷用には、レジスタ `D' を 1 に設定してください:
groff -Tps -rD1 -mdoc foo.man > foo.ps
ドキュメントのフォントサイズを 11pt や 12pt に変更したい 場合は、レジスタ `S' をそれに合わせて設定してください:
groff -Tdvi -rS11 -mdoc foo.man > foo.dvi
レジスタ `S' は TTY デバイスに対しては無視されます。
行およびタイトルの長さを変えたい場合、それぞれレジスタ `LL' と `LT' を設定してください:
groff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less
設定されていない場合、TTY デバイスに対してはレジスタ値は 78n に、 その他の場合 6.5i になります。
`. ' Sx NAME セクションにおいては、フォントを変更するべきです。
行の長さが短すぎる場合に行が分割されるのを防ぐために `.Fn がチェックを行う必要があります。 ' ときどき、最後の括弧が分割されることがあり、 行詰めモードであるときにおかしな結果になることがあります。
リストマクロおよびディスプレイマクロは何のキープも 行いませんが、これはキープを行うべきです。