GROFF_MDOC(7) FreeBSD 多方面の情報マニュアル GROFF_MDOC(7)
名称
|
groff_mdoc − groff mdoc の実装に関するリファレンス |
書式
|
groff −mdoc file ... |
|
解説 |
|
GNU troff(1) 用の コンテントベースでかつ 領域ベースな整形用パッケージであ る −mdoc マクロパッケージを使って UNIX マニュアルページを書くための完全な リファレンスです。前身である −man(7) パッケージは、フォントの操作や他の写 植方法の詳細は個々の作者に任せ、ページのレイアウトを取り扱ってきました。 −mdoc では、ページレイアウトマクロはタイトル、セクションのヘッダ、ディス プレイ、リストのマクロからなる ページ構造領域を形成しています。本質的にこ れらの要素は整形されたページにおけるテキストの物理的位置に影響を与えま す。ページ構造領域に加え、さらに マニュアル領域および 一般テキスト領域の 2 つの領域があります。一般テキスト領域は、テキストの一部をクォートしたり 強調したりといったような作業を実行するマクロとして定義されています。マ ニュアル領域はコマンドやルーチン、それに UNIX の関連ファイルを記述するた めの日常使用されるインフォーマルな言葉のサブセットであるマクロとして定義 されています。マニュアル領域のマクロはコマンド名、コマンド行の引数とオプ ション、関数名、関数のパラメータ、パス名、変数名、他のマニュアルページへ のクロスリファレンスなどを扱います。これらの領域の項目は作者とマニュアル ページの将来のユーザの両者にとって価値のあるものです。マニュアル間で一貫 性を高めることによって将来のドキュメントツールへの移行が容易になることが 期待されます。 UNIX マニュアルページ全体を通して、マニュアルのエントリは単純にマニュアル ページ (a man page) とみなされます。これは実際のページ数と関係ありません し、性差別をする意図もありません。 |
さあ、始めよう
|
このドキュメントの残りの部分で説明されている題材は以下のような構成になっ ています。 |
1. TROFF に特有な表現
|
マクロの使用方法 2. マニュアルページのテンプレート 3. 使用法 4. タイトルマクロ 5. マニュアル領域および一般テキスト領域の紹介 6. マニュアル領域 7. 一般テキスト領域 8. ページ構造領域 9. その他のマクロ 10.定義済みの文字列 11.診断 12.GROFF, TROFF および NROFF を使用した整形 13.関連ファイル 14.関連項目 15.バグ TROFF に特有な表現 |
|
−mdoc パッケージは、マニュアルページを記述するプロセスを簡単にすることを 目的としています。 −mdoc を使うために GNU troff(1) のゴタゴタした詳細を学 ぶ必要がないのが理想ですが、いくつか片付けるべき避けられない制限事項があ ります。また、このパッケージは高速で ないということも予め警告しておきま す。 |
|
マクロの使用方法 |
|
GNU troff(1) のように、マクロは ‘.’ (ドット) を行頭に置き、それに続けて 2 文字 (または 3 文字) からなるマクロの名称を指定することによって呼び出され ます。ドットとマクロの間にはスペースかタブを置くことができます。引数はマ クロの後にスペースで区切って指定することができます (タブは使用 できませ ん) 。行頭にドットを指定することによって GNU troff(1) にそれに続く 2 文字 (あるいはそれより多い文字) をマクロ名として解釈するよう指示しています。最 初にドット 1 文字をとり、その後ろに何も来ない場合は無視されます。マクロを 起動させたくないような文脈で、入力行の先頭に ‘.’ (ドット) を置くために は、 ‘.’ (ドット) の前にエスケープシーケンス ‘\&’ を指定します。 ‘\&’ は 文字通りスペース幅が 0 として解釈され、出力には現れません。 一般的に GNU troff(1) マクロは取り得る引数の数に制限はありません (9 つ以 上の引数を扱うことのできない他のバージョンの troff とは違います)。限られ た場合ではありますが、引数を次の行に続けたり、拡張したりすることができま す (後述の 拡張引数のセクションを参照)。ほとんどすべてのマクロで引用符に 囲まれた引数を扱うことができます (後述の 引数に空白文字を指定するのセク ションを参照)。 −mdoc での一般テキスト領域とマニュアル領域のほとんどのマクロは、呼び出し 可能なマクロ名を決定するためにその引数のリストが 構文解析されるという点で 特別なものです。これはつまり、一般テキスト領域またはマニュアル領域のマク ロ名に一致し (かつ、呼び出し可能であると定義された) 引数リスト中の引数 は、処理される時に実行されるか、もしくは呼び出されるということです。この 場合、引数がマクロの名前であっても ‘.’ (ドット) で前置されません。このよ うにしてたくさんのマクロを入れ子にすることができます。例えばオプションマ クロ ‘.Op’ はフラグマクロおよび引数マクロ ‘Fl’ と ‘Ar’ を 呼び出して、オ プションのフラグを引数とともに指定することができます: |
[−s bytes]
|
は ‘.Op Fl s Ar bytes’ で生成されます。 文字列がマクロ名と解釈されないようにするには、その文字列の前にエスケープ シーケンス ‘\&’ を指定します。 [Fl s Ar bytes] ここで文字列 ‘Fl’ と ‘Ar’ はマクロとして解釈されていません。このドキュメ ントを通じて、呼び出し可能な引数を調べるために引数リストが構文解析される マクロは 構文解析されるマクロとして参照し、引数リストから呼び出されること ができるマクロは 呼び出し可能なマクロとして参照します。 −mdoc のマクロは ほとんどすべてが構文解析されるのですから、これは技術的には 適当でない表現 ですが、常にマクロを「呼び出し可能である」とか「他のマクロを呼び出すこと ができる」と表現するのは面倒なことであるため、「構文解析される」という用 語を使います。 以降、この区別が必要な場合、行頭 (でドットで開始する) −mdoc マクロを コマ ンドと呼びます。 引数に空白文字を指定する 空白を含む引数を指定するには 2 通りの方法があります。 1 つは、空白を含む 文字列を渡すのに、固定の空白、つまりパディングされない空白文字 ‘\ ’ を使 う方法です。すなわち、空白の前にエスケープ文字 ‘\’ を指定します。この方法 はどのマクロでも使うことができますが、1 行が長くなり過ぎたテキストを調整 するときの邪魔になるという副作用があります。 troff では、固定の空白は他の 印刷可能な文字と同様に扱われ、通常期待されるようにその箇所で文字列を空白 や改行で分けることは行われなくなります。この方法は文字列が行の境界にまた がることが好ましくない場合に有用です。代替案としては、パディング可能 (す なわち伸長可能) で分割不可能な空白 ‘\~’ を使うことがあります (これは、 GNU troff(1) 拡張です)。 2 つ目の方法は、文字列をダブルクォートで括ること です。 例えば、次のようにします: fetch(char *str) fetch(char *str) もし、最初の例の空白の前もしくは次の例のダブルクォートの前の ‘\’ が省略さ れていた場合には ‘.Fn’ は引数が 3 つであるとみなし、その結果は fetch(char, *str) となります。 行末の空白文字 特殊文字のエスケープ その他の注意点 先頭に空白を置くと行分割が生じ、そのまま出力されてしまいます。可能ならば こうなることを避けてください。同様に、通常のテキスト行において単語間に 2 つ以上の空白文字を使用しないでください。これは、他のテキストフォーマッタ とは対照的です。空白文字を 2 つ以上置いても 1 つの空白文字に置き換わり ま せん。 引数として ‘"’ を直接渡すことはできません。代わりに ‘\*[q]’ (あるいは ‘\*q’) を使用してください。 デフォルトでは、 troff(1) は文を終了させる句読点の後に空白文字を 2 つ挿入 します。つまり、 ‘)’ あるいは ‘’’ などの文字はそのまま扱われ、文の終了に は影響を与えません。この動作を変更するには、ドットの前あるいは後に ‘\&’ を挿入してください。 The は、 The ‘’. character. The ‘.’ character. test. test test. test |
|
となります。 1 行目および 3 行目にみられるように、 −mdoc はマクロ引数の中では句読点を 特別に扱います。これについては、後述の 一般的な構文の節で述べます。同様の 方法で、幅 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
このテンプレートにおける最初のコマンドはマクロ ‘.Dd’, ‘.Os’, および ‘.Dt’ であり、それぞれドキュメントの日付、マニュアルページもしくは題材となって いるソースの開発や変更の対象となったオペレーティングシステム、そしてマ ニュアルページのタイトルを属するマニュアルのセクション番号とともに (大文 字で) 指定したもの、となっています。これらのコマンドはそのページを識別す るものであり、後述の タイトルマクロで解説されます。 テンプレート中の残りの項目はセクションのヘッダ (.Sh) であり、それらのうち NAME, SYNOPSIS, および DESCRIPTION は必須項目です。これらのヘッダについて は マニュアル領域を説明した後、 ページ構造領域で解説されます。いくつかの コンテントマクロはページレイアウトマクロの説明に使用されていますので、 ページレイアウトマクロの前にコンテントマクロについて読むことを推奨しま す。 |
使用法
|
次に説明するマクロはすべて、オプションの引数は角括弧 ([]) で括られます。 省略符号 (‘...’) はさらに 0 個以上の引数があることを表しています。パラ メータの代替値は ‘|’ で区切って示します。必須パラメータに代替値がある場合 は、 (‘|’ と一緒に) 中括弧 ({}) を用い、値の組を括ります。メタ変数は山括 弧 (<>) の中で指定されます。 例: |
.Xx ⟨foo⟩ {bar1 | bar2} [−test1 [−test2 | −test3]] ...
|
とくに明示しない限り、すべてのマクロは構文解析され、呼び出し可能なもので す。 マクロの効果が持続するのは、次のネストしたマクロまでであることに注意して ください。例えば ‘.Ic foo Aq bar’ は ‘foo <bar>’ とはならず ‘foo ⟨bar⟩’ となります。この結果、最初の引数がマクロである場合、ほとんどのコマンドに 対して警告が出力されます。マクロがコマンド呼び出しの効果を完全に打ち消し てしまうからです。また、マクロをクォートしても、文字通りのクォートは挿入 されないことは重要です。 ‘foo <bar>’ は ‘.Ic "foo <bar>"’ から生成されま す。 大部分のマクロはデフォルトの幅の値を持っており、これを ‘.Bl’ および ‘.Bd’ マクロ用にラベル width (−width) あるいは offset (−offset) を指定するのに 使用することができます。 −mdoc パッケージのローカルな変更に依存することの ないように、このとても曖昧な機能は使わないことを推奨します。 タイトルマクロ |
|
タイトルマクロはページ構造領域の一部ですが、マニュアルページを昨日書き始 めようと思ったという人のために、最初に、他のとは別に記述されています。 3 つのヘッダマクロでドキュメントまたはマニュアルページのタイトル、オペレー ティングシステム、および原著の日付を指定します。これらのマクロはドキュメ ントの最初で一度だけ呼び出されるもので、ヘッダとフッタを構成するためだけ に使用されます。 |
.Dt [⟨ドキュメントタイトル⟩] [⟨セクション番号⟩] [⟨ボリューム⟩]
|
ドキュメントタイトルはマニュアルページの主題であり、 troff の制限 により 大文字でなければいけません。省略された場合、 ‘UNTITLED’ が 使われます。セクション番号は 1, ..., 9 の範囲の番号もしくは ‘unass’, ‘draft’, ‘paper’ のいずれかを取ることができます。セク ション番号が指定されており、ボリューム名が与えられていない場合に は、デフォルトのボリューム名が使用されます。 FreeBSD 10.0 では、次のセクションが定義されています: |
|
1 FreeBSD 一般コマンドマニュアル |
|
2 FreeBSD システムコールマニュアル |
|
3 FreeBSD ライブラリ関数マニュアル |
|
4 FreeBSD カーネルインタフェースマニュアル |
|
5 FreeBSD ファイルフォーマットマニュアル |
|
6 FreeBSD ゲームマニュアル |
|
7 FreeBSD 多方面の情報マニュアル |
|
8 FreeBSD システム管理者マニュアル |
|
9 FreeBSD カーネル開発者マニュアル |
|
ボリューム名は任意であるか、もしくは次のものを取ることができます: |
|
USD User’s Supplementary Documents 互換性を保つため、 ‘IND’ の代わりに ‘MMI’ を使用することができ、 ‘LOCAL’ の代わりに ‘LOC’ を使用できます。先の表の値は、新しいボ リューム名を指定します。第 3 パラメータがコンピュータアーキテク チャを表すキーワードである場合、その値は第 2 パラメータで指定した ボリューム名の前に追加されます。デフォルトでは次のアーキテクチャ に関するキーワードが定義されています: 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 を正当 な数値として解釈されないようにしている点に注意してください。 |
.Dt FOO 7
|
‘FOO(7)’ ‘FreeBSD
多方面の情報マニュアル’ ローカルな追加項目や OS に特化した追加項目が、ファイル mdoc.local にあるかもしれません。このファイル中で ‘volume-ds-XXX’ (前者のタ イプについて) および ‘volume-as-XXX’ (後者のタイプについて) とい う名前の文字列を検索してください。ここで ‘XXX’ は ‘.Dt’ マクロで 使用されるキーワードを表しています。 このマクロは呼び出し不可能であり、構文解析もされません。 |
.Os [⟨オペレーティングシステム⟩] [⟨リリース番号⟩]
|
第 1 パラメータが空の場合、デフォルト値 ‘FreeBSD 10.0’ が使用され ます。これは、ローカルの設定ファイル mdoc.local で上書きできま す。一般的には、オペレーティングシステムの名称には一般的な頭字語 (略称) を使わなければなりません。例えば BSD や ATT といったもので す。リリース番号は、各システムでの標準のリリースの命名法を使用し ます。次の表では、いくつか事前に定義されているオペレーティングシ ステムに対して取り得る第 2 引数をリストしています。 ‘.Dt’ と同じ ように、ローカルな追加項目が mdoc.local に定義されているかもしれ ません。このファイル中で ‘operating-system-XXX-YYY’ という名前の 文字列を検索してください。ここで ‘XXX’ はオペレーティングシステム の頭字語 (略称) そして ‘YYY’ がリリース ID です。 |
ATT
|
7th, 7, III, 3, V, V.2, V.3, V.4 BSD NetBSD FreeBSD ATT に関しては、判別できない第 2 パラメータがある時にはそれを文字 列 UNIX に置き換えます。事前に定義されているその他の頭字語 (略称) については、そのようなパラメータは無視され、警告メッセージが出力 されます。認識できない引数は、ページフッタ中に記述された通りに表 示されます。例えば、典型的なフッタは次のようになるでしょう: |
|
.Os BSD 4.3 |
|
は ‘4.3 Berkeley Distribution’ となります。また、ローカルで作られ たセットの例では、 |
|
.Os CS Department |
|
は ‘CS Department’ となります。 ‘.Os’ マクロがない場合、ページの左下隅は見苦しくなってしまうで しょう。 このマクロは呼び出し不可能であり、構文解析もされません。 |
.Dd [ ⟨月⟩ ⟨日⟩, ⟨年⟩]
|
‘Dd’ に引数がない場合は、日付には ‘基準時点 (協定世界時 1970年1 月1日 00:00:00)’ が使用されます。ちょうど 3 つ引数がある場合に は、それらは連結され、分割できない空白で分けられたものになりま す。 .Dd January 25, 2001 それ以外の場合は現在の日付が使用され、パラメータは無視されます。 このマクロは呼び出し不可能であり、構文解析もされません。 マニュアル領域および一般テキスト領域の紹介 |
|
この名前には何が... |
|
マニュアル領域のマクロ名はコマンドやサブルーチン、それに関連ファイルを説 明するために使われている日常のインフォーマルな言葉から取られています。こ の言葉と少し違うバリエーションのものがマニュアルページを書く上での 3 つの 異なった側面を記述するのに使われます。最初のものは、 −mdoc マクロコマンド 使用方法の説明です。 2 番目は −mdoc マクロを 用いた UNIX コマンドの記述で す。 3 番目はコマンドを通常の言葉の感覚でユーザに示したものです。これはす なわち、マニュアルページのテキスト中でのコマンドの説明となります。 最初のケースでは、 troff(1) マクロはそれ自身、一種のコマンドとなっていま す。 troff コマンドは一般的に以下のような形式をとります。 .Xx argument1 argument2 ... ‘.Xx’ はマクロコマンドを示しており、それに続くものはすべて処理されるべき 引数として処理されます。 2 番目のケースでは、コンテントマクロを使用する UNIX コマンドの記述がもう少し含まれます。典型的な SYNOPSIS コマンド行はこ のように表示されます。 filter [−flag] ⟨ |
infile⟩ ⟨ outfile⟩
ここで filter はコマンド名であり、角括弧で囲まれた文字列 −flag は フラグ 引数で、これは角括弧で囲むことによってオプションであることを示していま す。 −mdoc の用語では、 ⟨
infile⟩ および ⟨ outfile⟩ は メタ引数と称されています。この例では、ユーザは山括弧 (<>) の中で与えられたメタ引数を実際のファイル名に置き換えなくてはなりません。このドキュメントでは、メタ引数は −mdoc コマンドを記述するのに使用していることに注意してください。多くのマニュアルページでは、メタ変数はわざわざ山括弧を使って書かれていません。上の例を整形したマクロは以下のものです。
.Nm filter
.Op Fl flag
.Ao Ar infile Ac Ao Ar outfile Ac
3 番目のケースでは、コマンドの説明や構文に上記の例の両方が使われ、さらに 細かい記述が追加されるでしょう。上の例での引数 ⟨
infile⟩ および ⟨ outfile⟩ は オペランドもしくは ファイル引数として参照されます。コマンド行の引数のリストはかなり長くなる場合もあります。
make
|
[−eiknqrstv] [−D variable] [−d flags] [−f makefile] [−I directory] [−j max_jobs] [variable=value] [target ...] ここではコマンド make について記述しており、 makefile をフラグ −f の引数 としています。またオプションのファイルオペランドである target についても 言及しています。言葉での説明では、こういった詳細な記述が混乱を防いでくれ ますが、 −mdoc パッケージにはフラグ への引数のためのマクロがありません。 その代わりに target のようなオペランドやファイル引数に使われる引数マクロ ‘Ar’ が 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 マクロ ‘.Bk’ および ‘.Ek’ は キープセクションにおいて解説されています。 |
|
一般的な構文 |
|
マニュアル領域のマクロと一般テキスト領域のマクロとはいくつか小さな違いが あるものの、同様な構文を使用しています。とりわけ、 ‘.Ar’, ‘.Fl’, ‘.Nm’, および ‘.Pa’ は引数なしで呼び出された時の違いしかありません。また、 ‘.Fn’ および ‘.Xr’ は引数のリストの順番が異なります。すべてのコンテントマクロが 句読点を認識し、それを正しく扱うには、各々の句読点文字が先行する空白で分 離されている必要があります。次のようにコマンドが指定されている場合、 |
|
.Ar sptr, ptr), |
|
その結果は以下のようになります。 |
|
sptr, ptr), |
|
ここでは句読点は認識されず、すべての出力は ‘.Ar’ で使用されるフォントで行 われています。句読点が空白文字で区切られている場合、 |
|
.Ar sptr , ptr ) , |
|
結果は以下のようになります。 |
|
sptr, ptr), |
|
今度は句読点が認識され、出力はデフォルトのフォントで行われ引数文字列とは 区別されています。句読点文字の特別な意味を取り除くには、 ‘\&’ でエスケー プしてください。 −mdoc は次の句読点文字を認識します。 |
|
. , : ; ( troff はマクロ言語としての限界から、以下のような、数学、論理学、引用符の 集合のメンバを含んだ文字列を表現するのは困難です。 {+,−,/,*,%,<,>,<=,>=,=,==,&,‘,’,"}
問題なのは、文字によって示唆されている操作もしくは評価が、実行されるべき であると troff が仮定する場合があることです。これらの文字が予期しない形で 評価されないようにするには、 ‘\&’ でこれらをエスケープしてください。最初 のコンテントマクロは、以下の ‘.Ad’ において、その典型的な構文が示されてい ます。 |
マニュアル領域
|
アドレス |
|
アドレスマクロはアドレスの構成を識別します。 |
|
使い方: .Ad ⟨ |
アドレス⟩ ...
.Ad addr1 addr1 .Ad addr1 . addr1. .Ad addr1 , file2 addr1, file2 .Ad f1 , f2 , f3 : f1, f2, f3: .Ad addr ) ) , addr)),
デフォルトの文字幅は 12n です。
作者名 ‘.An’ コマンドは文書化されている項目の作者の名前、もしくは実際のマニュアルページの作者の名前を指定するために使われます。
使い方: .An ⟨ 作者名⟩ ...
.An "Joe Author" Joe Author
.An "Joe Author" , Joe Author,
.An "Joe Author" Aq nobody@FreeBSD.org Joe Author ⟨nobody@FreeBSD.org⟩
.An "Joe Author" ) ) , Joe Author)),
デフォルトの文字幅は 12n です。
AUTHORS セクションでは、 ‘.An’ リクエストは改行を引き起こし、新しい名前がそれぞれの行に表示されます。この動作が望ましくない場合、
.An -nosplit
を呼び出すことで無効にできます。それぞれの行に表示させる動作に戻したい場 合は、
.An -split
と記述します。
|
引数 |
引数マクロ .Ar はコマンド行の引数を参照する際にはいつでも使用することがで きます。引数なしで呼ばれた場合、 ‘file ...’ が出力になります。
|
使い方: .Ar [ |
⟨ 引数⟩] ...
.Ar file ... .Ar file1 file1 .Ar file1 . file1. .Ar file1 file2 file1 file2 .Ar f1 f2 f3 : f1 f2 f3: .Ar file ) ) , file)),
デフォルト幅は 12n です。
コンフィギュレーション宣言 (セクション 4 のみ) ‘.Cd’ コマンドはセクション 4 のマニュアルにおいて、デバイスインタフェースの config(8) による宣言の説明に使われます。
使い方: .Cd ⟨ 引数⟩ ...
.Cd "device le0 at scode?" device le0 at scode?
SYNOPSIS セクションでは ‘.Cd’ リクエストはその引数が表示される前後で改行を入れます。
デフォルト幅は 12n です。
コマンド修飾子 コマンド修飾子は ‘.Cm’ マクロがすべての引数の前にダッシュ文字を付けないことを除いて、 ‘.Fl’ (フラグ) コマンドと同じです。伝統的にフラグはダッシュ文字に引き続いて指定されますが、この方法を使わないコマンドやコマンドのサブセットもあります。コマンド修飾子はエディタコマンドのような対話的なコマンドでも指定されることがあります。 フラグセクションを参照してください。
デフォルト幅は 10n です。
定義済みの変数 インクルードファイルにおいて定義されている変数 (もしくは定数) はマクロ‘.Dv’ によって指定します。
使い方: .Dv ⟨ 定義済みの変数⟩ ...
.Dv MAXHOSTNAMELEN MAXHOSTNAMELEN .Dv TIOCGPGRP ) TIOCGPGRP)
デフォルト幅は 12n です。
errno ‘.Er’ errno マクロは、セクション 2, 3, 9 のライブラリルーチンにおけるエラーの戻り値を指定します。下記の 2 番目の例では ‘.Er’ は一般テキスト領域マクロである ‘.Bq’ (これはセクション 2 のマニュアルページで使われています) と共に使われています。
使い方: .Er ⟨ errno のタイプ⟩ ...
.Er ENOENT ENOENT .Er ENOENT ) ; ENOENT); .Bq Er ENOTDIR [ENOTDIR]
デフォルト幅は 17n です。
環境変数 ‘.Ev’ マクロは環境変数を指定します。
使い方: .Ev ⟨ 引数⟩ ...
.Ev DISPLAY DISPLAY .Ev PATH . PATH. .Ev PRINTER ) ) , PRINTER)),
デフォルト幅は 15n です。
フラグ ‘.Fl’ マクロはコマンド行のフラグを扱います。フラグの前にはダッシュ ‘−’ が挿入されます。ダッシュがつかない対話的なコマンドのために ‘.Cm’ (コマンド修飾子) マクロが用意されています。これはダッシュを付けないことを除いて同じ働きをします。
使い方: .Fl ⟨ 引数⟩ ...
.Fl − .Fl cfv −cfv .Fl cfv . −cfv. .Cm cfv . cfv. .Fl s v t −s −v −t .Fl − , −−, .Fl xyz ) , −xyz), .Fl | − |
引数なしで ‘.Fl’ マクロを指定すると、標準入力/標準出力を意味するダッシュとなります。 ‘.Fl’ マクロにダッシュを 1 つ与えると、2 つのダッシュとなることに注意して下さい。
デフォルト幅は 12n です。
関数の宣言 ‘.Fd’ コマンドは SYNOPSIS セクションにおいて、セクション 2 または 3 の関数の説明で使われます。このマクロは呼び出し不可能であり、構文解析もされせん。
使い方: .Fd ⟨ 引数⟩ ...
.Fd "#include <sys/types.h>" #include <sys/types.h>
SYNOPSIS セクションでは、関数がすでに示されており、改行がまだされていない場合には ‘.Fd’ リクエストは改行を入れます。これによって前の関数呼び出しと次の関数の宣言の間に最適な行間が設定されます。
‘.In’ マクロは、 SYNOPSIS セクションで使用すると、 #include 文を表現するものであり、以上の例を短く記述したものです。このマクロは C プログラム中でインクルードされる C ヘッダファイルを指定します。このマクロも改行を挿入します。
SYNOPSIS セクション以外で使用すると、山括弧で括られたヘッダファイルを表現します。
使い方: .In ⟨ ヘッダファイル⟩
.In stdio.h #include <stdio.h> .In stdio.h <stdio.h>
関数の型 このマクロは SYNOPSIS セクションで使うものです。マニュアルページ中の他の場所でも問題なく使うことができますが、セクション 2 と 3 の SYNOPSIS セクションにおいてカーネルの通常の形式で関数の型を示すことがこのマクロの目的です (このマクロは関数名が次の行に置かれるように改行を挿入します)。
使い方: .Ft ⟨ 型⟩ ...
.Ft struct stat struct stat
関数 (ライブラリルーチン) ‘.Fn’ マクロは ANSI C の記法を規範としています。
使い方: .Fn ⟨ 関数⟩ [ ⟨ パラメータ⟩] ...
.Fn getchar getchar() .Fn strlen ) , strlen()), .Fn align "char *ptr" , align(char *ptr),
他のマクロを呼び出すと ‘.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
生成結果:
int
res_mkquery(int op, char *dname, int class, int type,char *data, int datalen, struct rrec *newrr, char *buf, int buflen)
SYNOPSIS セクションでは、関数は常に行の先頭から開始されます。 SYNOPSIS セ クションにおいて複数の関数が示されており、関数の型が示されない場合、改行 が挿入され、現在の関数名とその前の関数名の間に最適な改行量が設定されま す。
‘.Fn’ および ‘.Fo’ のデフォルト幅の値はそれぞれ 12n と 16n です。
|
関数の引数 |
‘.Fa’ マクロは関数の引数 (パラメータ) をマニュアルの SYNOPSIS のセクショ ン外で参照する場合、あるいは ‘.Fn’ の代わりに ‘.Fo’ および ‘.Fc’ 囲いマク ロを使用した場合には SYNOPSIS のセクション内で参照する場合にも使われま す。 ‘.Fa’ は構造体のメンバを参照する場合にも使われます。
|
使い方: .Fa ⟨ |
関数の引数⟩ ...
.Fa d_namlen ) ) , d_namlen)), .Fa iov_len iov_len
デフォルト幅は 12n です。
戻り値 ‘.Rv’ マクロは RETURN VALUES のセクションで使うテキストを生成します。
使い方: .Rv [ -std] [⟨ 関数⟩ ...]
例えば、 ‘.Rv -std atexit’ は次のテキストを生成します。
The atexit() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.
|
−std オプションはセクション 2 と 3 のマニュアルページでのみ有効です。現在 のところ、このマクロは −std フラグなしで使用しても何も起こりません。 |
|
終了ステータス |
|
‘.Ex’ マクロは DIAGNOSTICS のセクションで使うテキストを生成します。 |
|
使い方: .Ex [ |
-std] [⟨ ユーティリティ⟩ ...] 例えば ‘.Ex -std cat’ は次のテキストを生成します。
The cat utility exits 0 on success, and >0 if an error occurs.
|
−std オプションはセクション 1 と 6 と 8 のマニュアルページでのみ有効で す。現在のところ、このマクロは −std フラグなしで使用しても何も起こりませ ん。 |
|
対話的なコマンド |
|
‘.Ic’ マクロは対話的なコマンド、もしくは内部コマンドを指定します。 |
|
使い方: .Ic ⟨ |
引数⟩ ...
.Ic :wq :wq .Ic "do while {...}" do while {...} .Ic setenv , unsetenv setenv, unsetenv
デフォルト幅は 12n です。
ライブラリ名 ‘.Lb’ マクロは、関数がどのライブラリに組み込まれるかを指定します。
使い方: .Lb ⟨ 引数⟩ ...
‘.Lb’ マクロに対して使用可能な引数と結果は次の通りです:
libarm library ‘‘libarm’’ libarm32 ARM32 アーキテクチャライブラリ (libarm32, −larm32) libc 標準 C ライブラリ (libc, −lc) libcdk library ‘‘libcdk’’ libcompat 互換ライブラリ (libcompat, −lcompat) libcrypt 暗号ライブラリ (libcrypt, −lcrypt) libcurses curses ライブラリ (libcurses, −lcurses) libedit コマンドラインエディタライブラリ (libedit, −ledit) libevent library ‘‘libevent’’ libform library ‘‘libform’’ libi386 i386 アーキテクチャライブラリ (libi386, −li386) libintl library ‘‘libintl’’ libipsec IPsec ポリシ制御ライブラリ (libipsec, −lipsec) libkvm カーネルデータアクセスライブラリ (libkvm, −lkvm) libm 数値計算ライブラリ (libm, −lm) libm68k library ‘‘libm68k’’ libmagic library ‘‘libmagic’’ libmenu curses メニューライブラリ (libmenu, −lmenu) libossaudio OSS オーディオエミュレーションライブラリ (libossaudio,−lossaudio) libpam PAM Library (libpam, −lpam) libpcap library ‘‘libpcap’’ libpci library ‘‘libpci’’ libpmc library ‘‘libpmc’’ libposix POSIX 互換ライブラリ (libposix, −lposix) libpthread library ‘‘libpthread’’ libresolv DNS リゾルバライブラリ (libresolv, −lresolv) librt library ‘‘librt’’ libtermcap termcap アクセスライブラリ (libtermcap, −ltermcap) libusbhid USB HID access routines library (libusbhid, −lusbhid) libutil システムユーティリティライブラリ (libutil, −lutil) libx86_64 library ‘‘libx86_64’’ libz 圧縮ライブラリ (libz, −lz)
ローカルな追加項目や OS 特有の追加項目が、ファイル mdoc.local にあるかもしれません。 ‘str-Lb-XXX’ という名前の文字列を検索してください。ここで‘XXX’ は ‘.Lb’ マクロとともに使用されるキーワードを示しています。
ライブラリのセクションでは、 ‘.Lb’ コマンドは、引数の表示の前後でラインブレークを引き起こします。
リテラル リテラルマクロ ‘.Li’ は特殊文字や変数定数、その他タイプされた通りに表示する必要があるものに使用することができます。
使い方: .Li ⟨ 引数⟩ ...
.Li \en \n .Li M1 M2 M3 ; M1 M2 M3; .Li cntrl-D ) , cntrl-D), .Li 1024 ... 1024 ...
デフォルト幅は 16n です。
名称 ‘.Nm’ マクロは文書のタイトルやサブジェクト名を指定するために使われます。このマクロは呼び出された時の第 1 引数を覚えておくという変わった特性を持っており、それは常にそのページのサブジェクト名であるべきです。引数なしで呼び出されると ‘.Nm’ は作者のために最低限の仕事をするという意味で、この初期化された名称を出力します。注: セクション 2 または 3 のドキュメントの関数名は NAME セクションにおいて ‘.Nm’ で指定され、 SYNOPSIS セクションや残りのセクションでは ‘.Fn’ で指定されます。 csh(1) での ‘while’ コマンドのキーワードのような対話的なコマンドでは ‘.Ic’ マクロを使う必要があります。‘.Ic’ はほとんど ‘.Nm’ と同一ですが、それが使われたときの第 1 引数を記憶することはできません。
使い方: .Nm [ ⟨ 引数⟩] ...
.Nm groff_mdoc groff_mdoc .Nm \-mdoc −mdoc .Nm foo ) ) , foo)), .Nm : groff_mdoc:
デフォルト幅は 10n です。
オプション ‘.Op’ マクロはコマンド行の残りのすべての引数をオプションであることを示す角括弧で囲み、末尾の句読点は角括弧の外に置きます。 ‘.Oo’ マクロと ‘.Oc’マクロ (それぞれ開き角括弧と閉じ角括弧を生成します) は複数行に渡って使うことができ、また閉じ括弧の正確な位置を指定するのに使うことができます。
使い方: .Op [ ⟨ オプション⟩] ...
.Op [] .Op Fl k [−k] .Op Fl k ) . [−k]). .Op Fl k Ar kookfile [−k kookfile] .Op Fl k Ar kookfile , [−k kookfile], .Op Ar objfil Op Ar corfil [objfil [corfil]] .Op Fl c Ar objfil Op Ar corfil , [−c objfil [corfil]], .Op word1 word2 [word1 word2] .Li .Op Oo Ao option Ac Oc ... .Op [ ⟨ options⟩] ...
これは、 ‘.Oo’ マクロと ‘.Oc’ マクロを使った典型的な例です:
.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc
出力結果:
[
[−k kilobytes] [−i interval] [−c count]]
‘.Op’ マクロおよび ‘.Oo’ マクロのデフォルト幅はそれぞれ 14n と 10n です。
|
パス名 |
‘.Pa’ マクロはパス名もしくはファイル名を整形します。引数なしで呼ばれた場 合、 ‘~’ 文字列が出力となり、これは現在のユーザのホームディレクトリを表し ています。
|
使い方: .Pa [ |
⟨ パス名⟩] ...
.Pa ~ .Pa /usr/share /usr/share .Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX).
デフォルト幅は 32n です。
規格 ‘.St’ マクロは、規格の短縮名称を正式名称に置換します。
使い方: .St ⟨ 短縮名称⟩ ...
使用可能な ‘‘短縮名称/正式名称’’ の組は次の通りです:
ANSI/ISO C
-ansiC ANSI X3.159-1989 (‘‘ANSI C’’) -ansiC-89 ANSI X3.159-1989 (‘‘ANSI C’’) -isoC ISO/IEC 9899:1990 (‘‘ISO C89’’) -isoC-90 -isoC-99 ISO/IEC 9899:1999 (‘‘ISO C99’’)
POSIX パート 1: System API
-iso9945-1-90 ISO/IEC 9945-1:1990 (‘‘POSIX.1’’) -iso9945-1-96 ISO/IEC 9945-1:1996 (‘‘POSIX.1’’) -p1003.1 IEEE Std 1003.1 (‘‘POSIX.1’’) -p1003.1-88 IEEE Std 1003.1-1988 (‘‘POSIX.1’’) -p1003.1-90 ISO/IEC 9945-1:1990 (‘‘POSIX.1’’) -p1003.1-96 ISO/IEC 9945-1:1996 (‘‘POSIX.1’’) -p1003.1b-93 IEEE Std 1003.1b-1993 (‘‘POSIX.1’’) -p1003.1c-95 IEEE Std 1003.1c-1995 (‘‘POSIX.1’’) -p1003.1g-2000 IEEE Std 1003.1g-2000 (‘‘POSIX.1’’) -p1003.1i-95 IEEE Std 1003.1i-1995 (‘‘POSIX.1’’) -p1003.1-2001 IEEE Std 1003.1-2001 (‘‘POSIX.1’’) -p1003.1-2004
POSIX パート 2: シェルとユーティリティ
-iso9945-2-93 ISO/IEC 9945-2:1993 (‘‘POSIX.2’’) -p1003.2 IEEE Std 1003.2 (‘‘POSIX.2’’) -p1003.2-92 IEEE Std 1003.2-1992 (‘‘POSIX.2’’) -p1003.2a-92 IEEE Std 1003.2a-1992 (‘‘POSIX.2’’)
X/Open
-susv2 Version 2 of the Single UNIX Specification(‘‘SUSv2’’) -svid4 System V Interface Definition, Fourth Edition(‘‘SVID4’’) -xbd5 X/Open System Interface Definitions Issue 5(‘‘XBD5’’) -xcu5 X/Open Commands and Utilities Issue 5 (‘‘XCU5’’) -xcurses4.2 X/Open Curses Issue 4.2 (‘‘XCURSES4.2’’) -xns5 X/Open Networking Services Issue 5 (‘‘XNS5’’) -xns5.2 X/Open Networking Services Issue 5.2 (‘‘XNS5.2’’) -xpg3 X/Open Portability Guide Issue 3 (‘‘XPG3’’) -xpg4 X/Open Portability Guide Issue 4 (‘‘XPG4’’) -xpg4.2 X/Open Portability Guide Issue 4.2 (‘‘XPG4.2’’) -xsh5 X/Open System Interfaces and Headers Issue 5(‘‘XSH5’’)
その他
-ieee754 IEEE Std 754-1985 -iso8802-3 ISO/IEC 8802-3:1989
変数の型 ‘.Vt’ マクロは型を参照するときにはいつでも使用することができます。SYNOPSIS セクションでは改行が挿入されます (古いスタイルの変数宣言では便利です)。
使い方: .Vt ⟨ 型⟩ ...
.Vt extern char *optarg ; extern char *optarg; .Vt FILE * FILE *
変数 一般的な変数への参照です。
使い方: .Va ⟨ 変数⟩ ...
.Va count count .Va settimer , settimer, .Va "int *prt" ) : int *prt): .Va "char s" ] ) ) , char s])),
デフォルト幅は 12n です。
マニュアルページのクロスリファレンス ‘.Xr’ マクロは最初の引数にマニュアルページの名称をとります。オプションである第 2 引数は、文字列 (マニュアルセクションを定義します) であれば括弧で囲われます。
使い方: .Xr ⟨ マニュアルページの名称⟩ [ ⟨ セクション⟩] ...
.Xr mdoc mdoc .Xr mdoc , mdoc, .Xr mdoc 7 mdoc(7) .Xr xinit 1x ; xinit(1x);
デフォルト幅は 10n です。
一般テキスト領域
|
AT&T マクロ |
|
使い方: .At [ |
⟨ バージョン⟩] ...
.At AT&T UNIX .At v6 . Version 6 AT&T UNIX.
⟨ バージョン⟩ には次の値をとることができます:
32v, v1, v2, v3, v4, v5, v6, v7, V, V.1, V.2, V.3, V.4
BSD マクロ
使い方: .Bx { -alpha | -beta | -devel} ....Bx [ ⟨ バージョン⟩ [ ⟨ リリース⟩]] ...
.Bx BSD .Bx 4.3 . 4.3BSD. .Bx −devel BSD (currently under development)
⟨ バージョン⟩ が文字列 ‘BSD’ の前につきます。 ⟨ リリース⟩ には次の値をとることができます:
Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
NetBSD マクロ
使い方: .Nx [ ⟨ バージョン⟩] ...
.Nx NetBSD .Nx 1.4 . NetBSD 1.4.
⟨ バージョン⟩ にとり得る値については前述の タイトルマクロセクションの‘.Os’ コマンドの説明を参照してください。
FreeBSD マクロ
使い方: .Fx [ ⟨ バージョン⟩] ...
.Fx FreeBSD .Fx 2.2 . FreeBSD 2.2.
⟨ バージョン⟩ にとり得る値については前述の タイトルマクロセクションの‘.Os’ コマンドの説明を参照してください。
OpenBSD マクロ
使い方: .Ox [ ⟨ バージョン⟩] ...
.Ox 1.0 OpenBSD 1.0
BSD/OS マクロ
使い方: .Bsx [ ⟨ バージョン⟩] ...
.Bsx 1.0 BSD/OS 1.0
UNIX マクロ
使い方: .Ux ...
.Ux UNIX
強調マクロ テキストは ‘.Em’ マクロを用いて強調することができます。通常強調に用いられるフォントはイタリック体です。
使い方: .Em ⟨ 引数⟩ ...
.Em does not does not .Em exceed 1024 . exceed 1024. .Em vide infra ) ) , vide infra)),
デフォルト幅は 10n です。
フォントモード ‘.Bf’ フォントモードは ‘.Ef’ マクロで終了しなくてはなりません (後者のマクロは引数をとりません)。フォントモードは別のフォントモード内に入れ子にできます。
‘.Bf’ は次の文法をもっています:
.Bf ⟨ フォントモード⟩
⟨ フォントモード⟩ は次の 3 種類のうちのいずれかでなくてはなりません。
Em | −emphasis ‘.Em’ マクロがテキストのブロック全体に対して使用された場合と同じになります。 Li | −literal ‘.Li’ マクロがテキストのブロック全体に対して使用された場合と同じになります。 Sy | −symbolic ‘.Sy’ マクロがテキストのブロック全体に対して使用された場合と同じになります。
いずれのマクロも呼び出し不可能であり、構文解析もされません。
囲い/クォートマクロ 囲いの概念はクォートと似たものです。 1 つ以上の文字列が引用符や括弧のような文字のペアで囲まれているオブジェクトを指します。クォートと囲いという用語はこの文書を通して同じ意味で使われます。ほとんどの 1 行の囲いマクロはクォートであることをほのめかすために、小文字の ‘q’ で終了しますが、例外もいくつかあります。各々の囲いマクロに対し、開始マクロと終了マクロのペアもあり、それぞれ小文字の ‘o’ と ‘c’ で終了します。
クォート 開始 終了 機能 結果 |
|
.Aq |
.Ao |
.Ac |
山括弧による囲い |
⟨ |
|
string⟩ |
|
.Bq |
.Bo |
.Bc |
||||
|
角括弧による囲い |
[ |
|
string] |
|
.Brq |
.Bro |
.Brc |
||||
|
中括弧による囲い |
{ |
|
string} |
|
.Dq |
.Do |
.Dc |
||||
|
2 重引用符 |
‘‘ |
|
string’’ |
|
.Eq |
.Eo |
.Ec |
||||
|
囲い文字列 (XX による) |
XXstringXX |
|||||
|
.Pq |
.Po |
.Pc |
||||
|
括弧による囲い |
( |
|
string) |
|
.Ql |
||||||
|
クォートされたリテラル |
‘ |
|
string’ もしくは string |
|
|
.Qo |
.Qc |
||||
|
まっすぐな 2 重引用符 |
" |
|
string" |
|
.Sq |
.So |
.Sc |
||||
|
1 重引用符 |
‘ |
|
string’ |
|
‘q’ および ‘o’ で終わるマクロはすべてデフォルト幅が 12n です。 |
.Eo, .Ec
|
これらのマクロはそれぞれ第 1 引数に囲い始めに使う文字列と囲い終 わりに使う文字列をとります。 .Es, .En .Eq .Ql デフォルト幅は 16n です。 .Pf .Pf ( Fa name2 デフォルト幅は 12n です。 ‘.Ns’ マクロ (後述参照) は同じようにサフィックスに働きます。 .Ap クォートの例: .Aq 囲いマクロの入れ子についての良い例については、オプションマクロ ‘.Op’ を参 照してください。このマクロは上でリストされているような囲いマクロと同じ ベースの上に作られています。 ‘.Xo’ と ‘.Xc’ 拡張引数リストマクロについて は後で述べます。 無操作もしくは通常テキストマクロ 使い方: .No ⟨ .No test Ta with Ta tabs デフォルト幅は 12n です。 空白なしマクロ 使い方: ... ⟨ .Op Fl I Ns Ar directory 注: ‘.Ns’ マクロは他のマクロ名が続かなければ、スペースを除去したあとに ‘.No’ マクロを常に起動します。コマンドとして使用される場合 (つまり、 ‘使 い方’ の行での 2 番目の形式です)、 ‘.Ns’ マクロは ‘.No’ と同一です。 セクションのクロスリファレンス 使い方: .Sx ⟨ .Sx FILES デフォルト幅は 16n です。 記号 使い方: .Sy ⟨ .Sy Important Notice デフォルト幅は 6n です。 数学記号 使い方: .Ms ⟨ .Ms sigma デフォルト幅は 6n です。 参考文献と引用 .Rs ‘%’ で始まるマクロは呼び出し不可能ですが、通常の方法で複数の引数をとるこ とができます。パラメータとしては ‘.Tn’ マクロのみ扱います。その他のマクロ を使うと奇妙な出力が得られてしまいます。 ‘.%B’ および ‘.%T’ を ‘.Rs/.Re’ 環境の外側では使用することができます。 使用例: .Rs 出力結果 |
Matthew Bar and John Foo, Implementation Notes on foobar(1), Technical Report ABC-DE-12-345, Drofnats College, Nowhere, April 1991.
|
商標名 (頭字語とタイプ名) |
商標名マクロは、引数をより小さなフォントで出力します。意図される使い方 は、大文字の頭字語用に小さな大文字フォントを似せて作ることです。
|
使い方: .Tn ⟨ |
シンボル⟩ ...
.Tn DEC DEC .Tn ASCII ASCII
デフォルト幅は 10n です。
拡張引数 .Xo と .Xc マクロによって、 ‘.It’ マクロ (後述) についてマクロ境界での引数リストを拡張することができます。 .Xo と .Xc マクロは囲いを開いたり閉じたりする他のすべてのマクロに対して同じように実装されている (もちろん文字は挿入しません) ということに注意してください。つまり、次の例もこれらのマクロには当てはまります。
次は、スペーシングをオフにするために空白モードマクロを使った ‘.Xo’ の使用例です。
.Sm off
.It Xo Sy I Ar operation
.No \en Ar count No \en
.Xc
.Sm on
これは以下のような結果になります。
Ioperation\ncount\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]
|
囲いマクロを使った ‘.Xo’ の他の例: 変数の値をテストして下さい。 .It Xo .Ic .ifndef .Oo \&! Oc Ns Ar variable Oo .Ar operator variable ... .Oc Xc 結果は以下の通りです。 |
.ifndef [ !]variable [ operator variable ...]
ページ構造領域
|
セクションヘッダ |
|
次の ‘.Sh’ セクションヘッダマクロは、すべてのマニュアルページで必須のもの です。残りのセクションヘッダはマニュアルページの作者の裁量において、推奨 されているものです。 ‘.Sh’ マクロは構文解析されますが、一般的には呼び出し 不可能です。 ‘.Sh’ を呼び出すときだけは、このマクロは引数として使用するこ とができます。この場合、 ‘.Sh’ 用のデフォルトフォントを再度有効にします。 デフォルト幅は 8n です。 |
.Sh NAME
|
‘.Sh NAME’ マクロは必須です。これが指定されていない と、ヘッダとフッタ、それにデフォルトのページレイアウト が設定されず、結果はかなり好ましくないものになるでしょ う。 NAME セクションは最低 3 つの項目からなります。最 初のものは名称マクロ ‘.Nm’ であり、マニュアルページの サブジェクトとなります。 2 番目のものは名称説明マクロ ‘.Nd’ であり、サブジェクト名を 3 つめの項目、すなわち その名称の説明と分離します。説明に割り当てられるスペー スは小さいものですので、できるだけ簡潔で分かりやすいも のでなければなりません。 ‘.Nd’ は全ての引数の頭に ‘-’, を印字します。 .Sh LIBRARY .Sh SYNOPSIS cat [−benstuv] [−] file ... 次のマクロが使われています: |
|
.Nm cat |
|
.Op Fl benstuv |
|
.Op Fl |
|
.Ar |
.Sh DESCRIPTION
|
ほとんどの場合、 DESCRIPTION セクションでの最初のテキ ストはそのコマンド、関数もしくはファイルについての短い 段落で、オプションの構文リストとそれぞれの説明がそれに 続きます。そのようなリストを作成するには ‘.Bl’ (リスト 開始マクロ)、 ‘.It’ (リスト項目マクロ)、 ‘.El’ (リスト 終了マクロ) を使用します (後述の リストとカラムセク ションを参照)。 .Sh IMPLEMENTATION NOTES .Sh RETURN VALUES 次の ‘.Sh’ セクションヘッダはマニュアルページの好ましいレイアウトの一部で あり、一貫性を保つために適切に使われなければなりません。これらは使われる 順番にリストされています。 .Sh ENVIRONMENT .Sh FILES .Sh EXAMPLES .Sh DIAGNOSTICS .Sh COMPATIBILITY .Sh ERRORS .Sh SEE ALSO クロスリファレンスはセクション番号順、同一セクションに あるものはアルファベット順に並べ、コンマで区切ることを 推奨します。以下に例を示します: ls(1), ps(1), group(5), passwd(5) .Sh STANDARDS .Sh HISTORY .Sh AUTHORS .Sh BUGS ユーザ指定の ‘.Sh’ セクションを追加することができます。例えば、このセク ションは以下のように設定されています。 .Sh "ページ構造領域" |
|
サブセクションヘッダ |
|
サブセクションヘッダはセクションヘッダとまったく同じ文法をしています。 ‘.Ss’ は構文解析されますが、一般的に呼び出し不可能です。このマクロは、 ‘.Ss’ の呼び出し時にのみ引数として使用できます。このとき、 ‘.Ss’ のデフォ ルトフォントが再度有効になります。 デフォルト幅は 8n です。 |
|
段落と行スペース |
.Pp
|
‘.Pp’ 段落コマンドは必要な場合に行スペースを指定するために使われま す。このマクロは ‘.Sh’ マクロや ‘.Ss’ マクロの後、ならびに ‘.Bl’ マ クロや ‘.Bd’ マクロの前では必要ありません (いずれのマクロも −compact フラグが指定されていなければ垂直方向の距離を宣言します)。 このマクロは呼び出し不可能であり、構文解析もされません。そして引数を とりません。別名は ‘.Lp’ です。 キープ いずれのマクロも呼び出し不可能であり、構文解析もされません。 キープマクロについてはもっと作業をする必要があります。特に −line オプショ ンは追加する必要があるでしょう。 例示とディスプレイ .D1 −ldghfstru これは次の指定で生成されたものです: .D1 Fl ldghfstru .Dl % ls -ldg /usr/local/bin これは、次の指定で生成されたものです: .Dl % ls -ldg /usr/local/bin .Bd |
.Bd { −literal | −filled | −unfilled | −ragged |−centered} [ −offset ⟨ 文字列⟩] [ −file ⟨ ファイル名⟩] [ −compact]
−ragged
|
行詰めされますが、右マージンは調整しません (左マージン
のみです)。 left ⟨ .Ed リストとカラム さらに、タグ幅、リストのオフセット、コンパクトの度合 (項目間の空白行が許 されているかどうか) のようなリストの属性をいくつか指定することができま す。本ドキュメントのほとんどはタグ (−tag) スタイルリストで整形されていま す。 このマクロは次の文法規則を持っています: |
.Bl { −hang | −ohang | −tag | −diag | −inset} [ −width ⟨ 文字列⟩] [ −offset ⟨ 文字列⟩] [ −compact]
|
.Bl 次に、このリストタイプの詳細な解説を行います。 |
−bullet
|
ビュレットリストです。 .Bl -bullet -offset indent -compact 生成結果は次の通りです: |
• 1 つ目のビュレットはここにきます。
|
• 2 つ目のビュレットはここにきます。 −dash (または −hyphen) .Bl -dash -offset indent -compact 生成結果は次の通りです: |
− 1 つ目のダッシュはここにきます。
|
− 2 つ目のダッシュはここにきます。 −enum .Bl -enum -offset indent -compact 生成結果は次の通りです: |
1. 1 つ目の項目はここにきます。
|
2. 2 つ目の項目はここにきます。 箇条書きリストを入れ子にしたい場合、 −nested フラグを使用してく ださい (第 2 レベルのリストが開始されます): .Bl -enum -offset indent -compact 生成結果は次の通りです: |
1. 1 つ目の項目はここにきます。
|
1.1. 2 つ目の項目はここにきます。 −item .Bl -item -offset indent 生成結果は次の通りです: |
|
1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 |
−tag
|
タグつきリストです。タグ幅を指定するには −width を使用してくださ い。 SL 元のテキストは次の通りです: .Bl -tag -width "PPID" -compact -offset
indent |
−diag
|
診断リストはセクション 4 の診断リストを生成するもので、呼び出し 可能なマクロが無視されることを除き、inset リストと似ています。フ ラグ −width は、この文脈では意味がありません。 使用例: .Bl -diag 生成結果 ここで Sy を使うことはできません。 このメッセージはすべて出力さ れます。 |
−hang
|
ぶら下がりタグつきリストです。 Hangedラベル幅よりもラベルが小さい場合にはぶら下げられた ラベルはタグつきリストと同じように見えます。 Longer hanged list labelsラベル幅より長いぶら下がりリス トのラベルは、タグつき段落ラベルとは違い、段落に溶 け込みます。 以上の文章を生成した、整形前のテキストは次の通りです: .Bl -hang -offset indent |
−ohang
|
オーバハングタグ (overhanging tags) を用いたリストは項目に対して インデントを使いません。タグは別の行に出力されます。 SL PAGEIN UID PPID 元のテキストは次の通りです: .Bl -ohang -offset indent |
−inset
|
次は、inset ラベルの例です: tag タグリスト (タグ段落とも呼びます) はバークレーのマ ニュアルで使われている最も一般的な種類のリストです。後で述 べるように、 −width 属性を使用してください。 diag診断リストはセクション 4 の診断リストを生成し、呼び 出し可能なマクロを無視するという点を除けば inset リストと 似ています。 hangぶら下がりラベルは気分の問題です。 ohangオーバハングラベルは空白に制限がある場合には良いで す。 inset inset ラベルは段落ブロックを制御するのに便利で、 −mdoc マニュアルを別のフォーマットに変換するのに有用です。 上の例を生成したソーステキストはこうなっています: .Bl -inset -offset indent |
−column
|
この種類のリストは複数カラムを生成します。カラムの数および各カラ ムの幅は −column リストへの引数、 ⟨string1⟩, ⟨string2⟩ 等によっ て決定されます。 ⟨stringN⟩ が ‘.’ (ドット) で開始し直後に有効な −mdoc マクロ名が続く場合、 ⟨stringN⟩ を解釈して結果の幅を使用し ます。そうでない場合、 ⟨stringN⟩ (固定幅フォントでのタイプセッ ト) は N 番目の桁の幅になります。 ‘.It’ 引数はそれぞれ構文解析され行を生成します。行中の各列はタブ や ‘.Ta’ マクロで分けられた引数です。 次の表、 文字列 nroff troff は次のようにして生成されています: .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 その他のキーワード: |
−width ⟨ 文字列⟩
|
⟨文字列⟩ が ‘.’ (ドット) で開始し直後に有効な −mdoc マクロ名が 続く場合、 ⟨文字列⟩ を解釈し、その結果の幅を使います。本ドキュ メントのほとんどすべてのリストはこのオプションを使用していま す。 使用例: .Bl -tag -width ".Fl test Ao Ar 文字列 Ac" 生成結果: |
−test ⟨ 文字列⟩
|
これは、 −width フラグをタグリストと一緒に使うとどの ように働くかを見るためのもっと長い文です。 ⟨ そうでない場合、 ⟨文字列⟩ が正当な数値表現である場合 (‘u’ 以外 のスケール指示子を伴う) 、インデント用にその値を使用します。最 も有用なスケール指示子は ‘m’ と ‘n’ です。これらはいわゆる Em および En square を指定します。これらはそれぞれ、現在のフォン トでの文字 ‘m’ および文字 ‘n’ の幅とほぼ同じです (nroff の出力 については、どちらのスケール指示子でも同じ値が得られます)。 ⟨ 文字列⟩ が数値表現をしていない場合、文字列は −mdoc マクロ名で あるかどうか検査され、このマクロに関連するデフォルトのオフセッ ト値が使われます。最終的にすべてのテストが失敗した場合 ⟨文字 列⟩ の幅 (固定幅フォントでのタイプセット) がオフセットと見なさ れます。 タグリストタイプ用に幅が指定されていない場合、 ‘.It’ が起動さ れる度に適切な幅を決定しようと試みます。 ‘.It’ の第 1 引数が呼 び出し可能なマクロである場合、そのマクロのデフォルト幅が使われ ます。そうでなければ、 ‘.No’ のデフォルト幅が使われます。 −offset ⟨ −compact その他のマクロ |
|
ここには、いままでのセクションにはうまく当てはまらなかった残りのマクロの リストがあります。次のマクロに対しては本物の使用例を見つけられませんでし た。それは ‘.Me’ と ‘.Ot’ です。この 2 つについても完璧を期するためにここ に文書化はしています。もしこの 2 つのマクロの適切な使い方をご存知であれば bug-groff@gnu.org までメールを送ってください (例つきで)。 |
.Bt
|
は is currently in beta test. を表示します。 このマクロは呼び出し不可能であり、構文解析もされません。また引数もと りません。 |
.Fr
|
使い方: .Fr ⟨ このマクロは使わないでください。このマクロは戻り値 (通常は数字 1 個) の直前での改行を許してしまいます。印刷時の振る舞いとしては悪いことで す。直前の単語と戻り値とを結合させるには ‘\~’ を使用してください。 .Hf 使い方: .Hf ⟨ このマクロは呼び出し不可能であり、構文解析もされません。 .Lk .Me デフォルト幅は 6n です。 .Mt .Ot .Sm 使い方: .Sm [ 空白モードが off の場合、マクロ引数の間に空白は挿入されません。引数 なしで呼ばれた場合 (あるいは次の引数が ‘on’ でも ‘off’ でもない場合) ‘.Sm’ マクロは空白モードに入ります。 .Ud currently under development. を表示します。 このマクロは呼び出し不可能であり、構文解析もされません。また引数もと りません。 |
定義済み文字列
|
次の文字列が定義済みです: |
|
文字列 nroff troff 意味 カラムの名前 nroff と troff は少々誤解を招くものです。 nroff は ASCII 文 字を表示しますが、 troff では利用可能なもののうち一番良いグリフ形式を表示 します。例えば、Unicode を使用可能にした TTY デバイスはすべての文字列に対 して適切なグリフ表現を持っていますが、それに対して Latin1 に対して機能を 強化した TTY デバイスはプラスマイナス記号しか持っていません。 文字を 2 つ含んだ文字列名は ‘\*(xx’ として表記できます。文字を 1 文字だけ 含んだ文字列名は ‘\*x’ と表記できます。どのような長さの文字列名に対して も、一般的な文法は ‘\*[xxx]’ となります ( これは GNU troff(1) 拡張です)。 |
診断
|
以前のバージョンの −mdoc パッケージでは利用可能だったデバッグ用マクロ ‘.Db’ は取り除かれました。なぜなら、 GNU troff(1) ではパラメータをチェッ クするのにもっと良いファシリティを提供しているからです。さらに、このマク ロパッケージにはエラーや警告メッセージが多数追加されており、よりロバスト で饒舌なものになっています。 唯一残ったデバッグ用マクロは ‘.Rd’ であり、これはすべてのグローバルレジス タならびに文字列のレジスタダンプを出力するものです。通常のユーザが使う必 要は決してないでしょう。 |
GROFF, TROFF, および NROFF を使用した整形
|
デフォルトでは、このパッケージでは ‘latin1’ や ‘unicode’ のような TTY デ バイスで表示する場合には改ページやヘッダ、フッタは禁止されており、マニュ アルをオンラインで効率良く見ることができるようになっています。この振る舞 いは、 groff(1) を呼んでいるときにレジスタ ‘cR’ に 0 を指定することで変更 することができます (例えば、 TTY 出力のハードコピーを作成したいときな ど)。 |
|
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 になります。 |
関連ファイル
doc.tmac
|
主なマニュアル用マクロパッケージです。 関連項目 |
バグ
|
セクション 3f はヘッダルーチンには追加されていません。 ‘.Nm’ NAME セクションにおいては、フォントを変更するべきです。 行の長さが短すぎる場合に行が分割されるのを防ぐために ‘.Fn’ がチェックを行 う必要があります。ときどき、最後の括弧が分割されることがあり、行詰めモー ドであるときにおかしな結果になることがあります。 リストマクロおよびディスプレイマクロは何のキープも行いませんが、これは キープを行うべきです。 FreeBSD 10.0 July 8, 2004 FreeBSD 10.0 |