MDOC.SAMPLES(7) | FreeBSD Miscellaneous Information Manual | MDOC.SAMPLES(7) |
名前
mdoc.samples — -mdoc を使って BSD マニュアルを書くためのチュートリアルサンプル書式
man mdoc.samples説明
troff(1) 用の コンテントベース でかつ 領域ベース なフォーマットパッケージである -mdoc マクロパッケージを使って BSD マニュアルを書くためのチュートリアルサンプルです。前身である -man(7) パッケージはフォントの操作や他の写植方法の詳細は個々の作者に任せたページレイアウトベースのものでした。 -mdoc では、ページレイアウトマクロはタイトル、セクションのヘッダ、ディスプレイ、リストのマクロからなる ページ構造領域 を形成しています。これらの項目は整形されたページでのテキストの物理的な位置に影響を持ちます。ページ構造領域に加え、さらにマニュアル領域および一般テキスト領域の 2 つの領域があります。一般テキスト領域はテキストの一部をクォートしたり、強調するといったような作業を実行するマクロとして定義されています。マニュアル領域はコマンドやルーチン、それに BSD の関連ファイルを記述するための日常使用されるインフォーマルな言葉のサブセットであるマクロとして定義されています。マニュアル領域のマクロはコマンド名、コマンド行の引数とオプション、関数名、関数のパラメータ、パス名、変数名、他のマニュアルページへのクロスリファレンスなどを扱います。これらの領域の項目は作者とマニュアルページの将来のユーザの両者にとって価値のあるものです。マニュアル間で一貫性を高めることによって将来のドキュメントツールへの移行が容易になることが望まれます。マニュアルのエントリは、実際の長さに関わらず、また男女の区別をするような意図なしで、 UNIX のマニュアルページを通して、単純に man ページとして参照されています。
さあ、始めよう
通常チュートリアルドキュメントは、そこに示された題材をすぐに使いたい時に読むものですので、このドキュメントのユーザはせっかちな人だと仮定しています。このドキュメントの残りの部分で説明されている題材は以下のような構成になっています。- TROFF に特有な表現
- マクロの使用方法
- 引数に空白文字を指定する
- 行末の空白文字 (警告)
- 特殊文字のエスケープ
- MAN ページの分析
- マニュアルページのテンプレート
- タイトルマクロ
- マニュアルと一般テキスト領域の紹介
- この名前には何が...?
- 一般的な構文
- マニュアル領域
- アドレス
- 作者名
- 引数
- コンフィギュレーション宣言 (セクション 4 のみ)
- コマンド修飾子
- 定義済みの変数
- errno (セクション 2 のみ)
- 環境変数
- 関数の引数
- 関数の宣言
- フラグ
- 関数 (ライブラリルーチン)
- 関数の型
- 対話的なコマンド
- 名前
- オプション
- パス名
- 変数
- 相互参照
- 一般テキスト領域
- AT&T マクロ
- BSD マクロ
- FreeBSD マクロ
- UNIX マクロ
- 囲い/クォートマクロ
-
- カギ括弧 <>によるクォート/囲い
- 角括弧 [] によるクォート/囲い
- 二重引用符マクロ/囲い
- 括弧 () によるクォート/囲い
- 一重引用符によるクォート/囲い
- プレフィックスマクロ
- no-op もしくは通常テキストマクロ
- 空白なしマクロ
- セクションの相互参照
- 相互参照と引用
- 返り値 (セクション 2, 3 のみ)
- 商標名 (頭字語とタイプ名)
- 拡張引数
- ページ構造領域
- セクションヘッダ
- 段落と行スペース
- キープ
- ディスプレイ
- フォントモード (強調、リテラル、およびシンボリック)
- リストと列
- 定義済みの文字列
- 診断
- GROFF、TROFF、NROFF を使用したフォーマッティング
- バグ
TROFF に特有な表現
-mdoc パッケージは man ページを記述するプロセスを簡単にすることを目的としています。 -mdoc を使うために troff(1) のゴタゴタした詳細を学ぶ必要がないのが理想ですが、いくつか片付けるべき避けられない制限事項があります。また、このパッケージは高速で ない ということも予め警告しておきます。マクロの使用方法
troff(1) のように、マクロは‘.
’ (ドット文字) を行頭に置き、それに続けて 2 文字からなるマクロの名称を指定することによって呼び出されます。引数はマクロの後にスペースで区切って指定することができます。行頭にドット文字を指定することによって
troff(1) にそれに続く 2 文字をマクロ名として解釈するよう指示しています。マクロを起動せずに、ある文脈の行の先頭に‘
.
’ (ドット文字) を置くためには、‘
.
’ (ドット) の前にエスケープシーケンス‘
\&
’を指定します。‘
\&
’は文字通りスペース幅が 0 として解釈され、出力には現れません。
一般的に troff(1) マクロは引数を 9 つまで取ることができ、それ以上指定された引数は無視されます。 -mdoc でのほとんどのマクロは 9 つの引数を取ることができ、限られた場合にのみ引数は次の行に続けて指定することができます ( 拡張引数 セクションを参照)。いくつかのマクロは引用符に囲まれた引数を扱うことができます (下の 引数に空白文字を指定する セクションを参照)。
-mdoc での一般テキスト領域とマニュアル領域のほとんどのマクロは特別であり、その引数のリストは呼び出し可能なマクロ名として 解析 されます。これは一般テキスト領域またはマニュアル領域のマクロ名に一致し、呼び出し可能であると判断された引数リストの中の引数は、実行されるか、それが処理される時に呼び出されることを意味しています。この場合、引数はマクロ名にも関わらず、‘ .
’ (ドット) で前置されません。このようにしてたくさんのマクロを入れ子にすることができます。例えばオプションマクロ‘ .Op
’はフラグマクロ‘ Fl
’と引数マクロ‘ Ar
’を 呼び出して 、オプションのフラグを引数とともに指定することができます。
- [ -s bytes]
-
は
.Op Fl s Ar bytes
によって生成される
2 文字からなる文字列をマクロ名として解釈されないようにするには、その文字列の前にエスケープシーケンス‘ \&
’を指定します。
- [ Fl s Ar bytes]
-
は
.Op \&Fl s \&Ar bytes
によって生成される
ここで文字列‘ Fl
’と‘ Ar
’はマクロとして解釈されていません。本ドキュメントと関連のクイックリファレンスマニュアル mdoc(7) を通して、引数リストが呼び出し可能な引数として解析されるマクロは「解析される」、引数リストから呼び出されることができるマクロは「呼び出し可能」と表現します。 -mdoc のほとんどすべてのマクロは解析されるのですから、これは技術的には 不謹慎な ことですが、常にマクロを「呼び出し可能である」とか「他のマクロを呼び出すことができる」と表現するのは面倒なことであるため、「解析される」という用語が使われています。
引数に空白文字を指定する
ひとつ以上の空白文字を含む文字列をひとつの引数として指定したい場合がよくあります。これは 9 個を越える引数を指定できないという制限に対処したり、引数のリストにある特有な配置をおこなうことが必要なマクロに引数を指定するような場合に必要となることがあります。たとえば、関数マクロ‘.Fn
’では最初の引数は関数名であり、残りの引数が関数のパラメータであることが必要です。 ANSI C の括弧で囲まれたパラメータリストにおける関数のパラメータの宣言の規定により、各パラメータは最低でも 2 語の文字列となります。たとえば
int foo のようになります。
空白を含む引数を指定するには 2 通りの方法があります。 実装上の注意: 解析の前に個々の引数を再割り当てすることによって、引用符の間に空白を含めて渡すのが最も便利な方法なのですが、 AT&T の troff のすべてのマクロを実装するには処理速度およびメモリ使用量の点でかなり高価な方法となります。 groff では高価な処理にはなりませんが、移植性のため、この方法は空白を含めることが最も必要である以下のマクロだけに限っています。
-
Cd
- コンフィギュレーション宣言 (セクション 4 の SYNOPSIS)
-
Bl
- リスト開始 (幅指定用)
-
Em
- テキスト強調
-
Fn
- 関数 (セクション 2 と 4)
-
It
- リストの項目
-
Li
- リテラルテキスト
-
Sy
- シンボリックテキスト
-
%B
- 書籍のタイトル
-
%J
- 定期刊行物のタイトル
-
%O
- 参照の追加的な注釈
-
%R
- 報告書のタイトル (参照の中で)
-
%T
- 書籍や定期刊行物の中の記事のタイトル
空白を含む文字列を渡すのに、固定空白、すなわち詰め込まれない空白文字‘ \
’を使う方法があります。すなわち、空白の前にエスケープ文字‘ \
’を指定する方法です。この方法はどのマクロでも使うことができますが、1 行を越える長さのテキストの調整の邪魔になるという副作用があります。 Troff では固定空白は他の印刷可能文字と同様に扱われ、通常期待されるように、そこで文字列を空白や改行で分けることを行なわなくなります。この方法は文字列が行の境界をまたがないであろう場合に有用です。例えば、
- fetch( char *str)
-
は‘
.Fn fetch char\ *str
’によって生成される - fetch( char *str)
-
は‘
.Fn fetch "char *str"
’でも生成される
もし‘ \
’や引用符が省かれると、‘ .Fn
’は引数を 3 つ取り、その結果は以下のようになります。
fetch( char, *str)
パラメータのリストが改行の境界をまたぐ場合に何がおこるかについては、 バグ のセクションを参照してください。
行末の空白文字
Troff は行末に空白文字があると混乱してしまうことがあります。 <空白> <行末>の文字シーケンスからすべての空白文字を取り除くのは良い予防策です。どうしても行末に空白文字をおく必要性が出てきた場合は、詰め込まれない空白とエスケープ文字‘\&
’を使用することによって対応できます。例えば、‘
string\ \&
’のようにします。
特殊文字のエスケープ
改行‘\n
’のような特殊文字は‘
\
’を‘
\e
’で置き換える (すなわち‘
\en
’とする) ことによって、バックスラッシュを残して扱うことができます。
MAN ページの分析
man ページの本文はファイル /usr/share/misc/mdoc.template の基本テンプレートを使って容易に作り上げることができます。 /usr/share/examples/mdoc にはいくつかのサンプルの man ページが収められています。
マニュアルページのテンプレート
.\"以下の項目はすべての man ページで必要な項目です。 .Dd 月日, 年 .Os オペレーティングシステム [バージョン/リリース] .Dt ドキュメントタイトル [セクション番号] [ボリューム] .Sh NAME .Nm 名前 .Nd 名前の 1 行での説明 .Sh SYNOPSIS .Sh DESCRIPTION .\"以下の項目については、必要に応じてコメントをはずして .\"使用してください。 .\"この次の項目はセクション 2, 3, 9 でのみ必要な、関数の .\"戻り値です。 .\" .Sh RETURN VALUE .\"次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。 .\" .Sh ENVIRONMENT .\" .Sh FILES .\" .Sh EXAMPLES .\"次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。 .\" ((シェルへの) コマンドの戻り値と .\" fprintf/stderr の型の診断です。) .\" .Sh DIAGNOSTICS .\"次の項目はセクション 2, 3, 9 でのみ必要な、 .\"エラーハンドリングとシグナルハンドリングです。 .\" .Sh ERRORS .\" .Sh SEE ALSO .\" .Sh CONFORMING TO .\" .Sh HISTORY .\" .Sh AUTHORS .\" .Sh BUGS
このテンプレートにおける最初の項目はマクロ ( .Dd
, .Os
, .Dt
) であり、それぞれドキュメントの日付、 man ページもしくは題材となっているソースの開発や変更のベースとなったオペレーティングシステム、 ( 大文字で) man ページタイトルをそのページが属するマニュアルのセクション番号とともに指定したもの、となっています。これらのマクロはそのページを識別するものであり、後述の タイトルマクロ で議論されています。
テンプレート中の残りの項目はセクションのヘッダ ( .Sh
) であり、それらのうち NAME と SYNOPSIS と DESCRIPTION は必須項目です。これらのヘッダについては マニュアル領域 を説明した後、 ページ構造領域 で議論されます。いくつかのコンテントマクロはページレイアウトマクロの説明に使われていますので、ページレイアウトマクロの前にコンテントマクロについて読むことを推奨します。
タイトルマクロ
タイトルマクロはページ構造領域の最初の部分ですが、man ページを前日に書き始めたいという人のために、最初に分けて記述されます。 3 つのヘッダマクロでドキュメントか man ページのタイトル、オペレーティングシステム、および原著の日付を指定します。これらのマクロはドキュメントの最初に一度だけ呼び出されるもので、ヘッダとフッタを構成するためだけに使用されます。-
.Dt ドキュメントタイトルセクション番号 [ボリューム]
-
ドキュメントタイトルは man ページの主題であり、troff の制限により大文字でなければいけません。セクション番号は 1, ..., 8 となり、これが指定されるとボリュームタイトルを省略してもかまいません。では、次のセクション番号と解説について後述します: ボリュームタイトルには任意のものか次のいずれかを指定します。
AMD
UNIX Ancestral Manual Documents SMM
UNIX System Manager's Manual URM
UNIX Reference Manual PRM
UNIX Programmer's Manual デフォルトのボリュームラベルはセクション 1, 6, 7 では
URM
、セクション 8 ではSMM
、セクション 2, 3, 4, 5 ではPRM
となっています。 -
.Os オペレーティングシステムリリース番号
-
オペレーティングシステムの名称には一般的な頭字語 (略称) を使わなければなりません。例えば、 BSD や FreeBSD や ATT といったものです。リリース番号は、例えば4.3, 4.3+Tahoe, V.3, V.4 というような各システムでの標準のリリースの命名法を使用します。認識されない引数はページのフッタ中に記述された通りに表示されます。以下にフッタの典型的な例を示します。
.Os 4.3BSD
や
.Os FreeBSD 2.2
やローカルで生成されたセット
.Os CS Department
Berkeley でのデフォルトである、引数なしの‘
.Os
’はサイト固有のファイル /usr/share/tmac/mdoc/doc-common において BSD として定義されています。これは実際には LOCAL として定義すべきです。‘.Os
’マクロがない場合は、ページの左下角は見にくくなるであろうことに注意してください。 -
.Dd 月日, 年
-
日付は次のようにフォーマルな形式で記述しなければなりません。
January 25, 1989
マニュアルと一般テキスト領域の紹介
この名前には何が...?
マニュアル領域のマクロ名はコマンドやサブルーチン、それに関連ファイルを説明するために使われている日常のインフォーマルな言葉から取られています。この言葉と少し違うバリエーションのものが man ページを書く上での 3 つの異なった面を記述するのに使われます。最初のものは -mdoc マクロ使用方法の説明です。 2 番目のものは -mdoc マクロを用いた UNIX コマンドの記述です。 3 番目はコマンドを通常の言葉の感覚でユーザに示したものです。これはすなわち、man ページのテキスト中でのコマンドの議論となります。最初のケースでは、 troff(1) マクロはそれ自身、一種のコマンドとなっています。 troff コマンドは一般的に以下のような形式をとります。
‘ .Va
’はマクロコマンドもしくは要求を示しており、それに続くものはすべて引数として処理されます。 2 番目のケースでは、コンテントマクロを使用する UNIX コマンドの記述がもう少し含まれます。典型的な SYNOPSIS コマンド行はこのように表示されます。
ここで filter はコマンド名であり、角括弧で囲まれた文字列 -flag は フラグ 引数で、これは角括弧で囲むことによってオプションであることを示しています。 -mdoc の用語では infile と outfile は 引数 と称されています。上の例のフォーマットを行なったマクロは以下のものです。
.Nm filter .Op Fl flag .Ar infile outfile
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=value .Bk -words .Op Ar target ... .Ek
マクロ‘ .Bk
’と‘ .Ek
’は キープ セクションにおいて解説されています。
一般的な構文
マニュアル領域と一般テキスト領域のマクロはいくつかの小さな違いがあるものの、同様な構文を使用しています。‘.Ar
’, ‘
.Fl
’, ‘
.Nm
’, ‘
.Pa
’は引数なしで呼び出された時のみ異なります。‘
.Fn
’と‘
.Xr
’は引数のリストの順番が異なります。マクロ‘
.Op
’と‘
.Fn
’には入れ子の制限があります。すべてのコンテントマクロが句読点を認識し、正しく扱うには、各々の句読点文字が先行する空白で分離されている必要があります。以下のように指定されている場合、
.Li sptr, ptr),
結果は以下のようになります。
sptr, ptr),
ここでは句読点は認識されずすべての出力はリテラルなフォントで行なわれています。句読点が空白文字で区切られている場合、
.Li sptr , ptr ) ,
結果は以下のようになります。
sptr
,ptr
),
今度は句読点が認識され、出力はデフォルトのフォントで行なわれリテラルフォントの文字列と区別されています。
‘ \&
’でエスケープすることによって句読点文字の特別な意味を取り除くことができます。 troff はマクロ言語としての限界から、数学、論理学、もしくは以下の引用符の集合のメンバを含んだ文字列を表現するのは困難です。
{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
troff が文字によって示唆されている操作もしくは評価を実際に行なっていることが、その問題の原因となっています。‘ \&
’でこれらをエスケープすることによって、これらの文字が予期せずに評価されることを防止することができます。最初のコンテントマクロは、以下の‘ .Ad
’において、その典型的な構文が示されています。
マニュアル領域
アドレスマクロ
アドレスマクロは addr1[,addr2[,addr3]] の形式からなるアドレスを識別します。
使い方: .Ad address ... [.,:;()[]?!]
-
.Ad addr1
- addr1
-
.Ad addr1 .
- addr1.
-
.Ad addr1 , file2
- addr1, file2
-
.Ad f1 , f2 , f3 :
- f1, f2, f3:
-
.Ad addr ) ) ,
- addr) ),
‘ .Ad
’を引数なしで呼び出すのはエラーです。‘ .Ad
’は他のマクロから呼び出し可能で解析されます。
作者名
‘.An
’マクロは文書化されている項目の作者の名前、もしくは実際のマニュアルページの作者の名前を指定するために使われます。名前の情報の後のすべての引数は句読点として扱われます。
使い方: .An author_name [.,:;()[]?!]
-
.An Joe Author
-
.An Joe Author ,
- ,
-
.An Joe Author Aq nobody@FreeBSD.ORG
- <nobody@FreeBSD.ORG>
-
.An Joe Author ) ) ,
- )
‘ .An
’マクロは解析され、呼び出し可能です。‘ .An
’を引数なしで呼び出すのはエラーです。
引数マクロ
引数マクロ‘.Ar
’はコマンド行の引数を参照する際に使用することができます。
使い方: .Ar argument ... [.,:;()[]?!]
-
.Ar
- file ...
-
.Ar file1
- file1
-
.Ar file1 .
- file1.
-
.Ar file1 file2
- file1 file2
-
.Ar f1 f2 f3 :
- f1 f2 f3:
-
.Ar file ) ) ,
- file) ),
‘ .Ar
’が引数なしで呼び出されると、‘ .Ar
’として扱われます。‘ .Ar
’マクロは解析され、呼び出し可能です。
コンフィギュレーション宣言 (セクション 4 のみ)
‘.Cd
’マクロはセクション 4 のマニュアルにおいて、デバイスインタフェースの
config(8) による宣言の説明に使われます。このマクロは引用符 (二重引用符のみ) で囲まれた引数を取ることができます。
- device le0 at scode?
-
は‘
.Cd device le0 at scode?
’によって生成されます。
コマンド修飾子
コマンド修飾子は‘.Cm
’マクロがすべての引数の前にダッシュ文字を付けないことを除いて、‘
.Fl
’ (フラグ) コマンドと同じです。伝統的にフラグはダッシュ文字に引き続いて指定されますが、いくつかのコマンドやコマンドのサブセットはこの方法を使っていません。コマンド修飾子はエディタコマンドのような対話的なコマンドでも指定されることがあります。
フラグ のセクションを参照してください。
定義済みの変数
インクルードファイルにおいて定義されている変数は‘.Dv
’マクロによって指定します。
使い方: .Dv defined_variable ... [.,:;()[]?!]
-
.Dv MAXHOSTNAMELEN
- MAXHOSTNAMELEN
-
.Dv TIOCGPGRP )
- TIOCGPGRP)
‘ .Dv
’を引数なしで呼び出すのはエラーです。‘ .Dv
’は解析され、呼び出し可能です。
errno (セクション 2 のみ)
エラーマクロ‘.Er
’はセクション 2 のライブラリルーチンにおけるエラーの戻り値を指定します。下記の 2 番目の例では‘
.Er
’は一般テキスト領域マクロである‘
.Bq
’ (これはセクション 2 のマニュアルページで使われています) と共に使われています。
使い方: .Er ERRNOTYPE ... [.,:;()[]?!]
-
.Er ENOENT
- ENOENT
-
.Er ENOENT ) ;
- ENOENT);
-
.Bq Er ENOTDIR
- [ ENOTDIR]
‘ .Er
’を引数なしで呼び出すのはエラーです。‘ .Er
’は解析され、呼び出し可能です。
環境変数
‘.Ev
’マクロは環境変数を指定します。
使い方: .Ev argument ... [.,:;()[]?!]
-
.Ev DISPLAY
- DISPLAY
-
.Ev PATH .
- PATH.
-
.Ev PRINTER ) ) ,
- PRINTER) ),
‘ .Ev
’を引数なしで呼び出すのはエラーです。‘ .Ev
’は解析され、呼び出し可能です。
関数の引数
‘.Fa
’マクロは関数の引数 (パラメータ) をマニュアルの
SYNOPSIS のセクション外、もしくは
SYNOPSIS のセクション内で参照する場合に使われます。パラメータのリストが‘
.Fn
’マクロでは長すぎる場合は、囲って使うマクロ‘
.Fo
’と‘
.Fc
’を使わなければなりません。‘
.Fa
’は構造体のメンバを参照する場合にも使われます。
使い方: .Fa function_argument ... [.,:;()[]?!]
-
.Fa d_namlen ) ) ,
- d_namlen) ),
-
.Fa iov_len
- iov_len
‘ .Fa
’を引数なしで呼び出すのはエラーです。‘ .Fa
’は解析され、呼び出し可能です。
関数の宣言
‘.Fd
’マクロは
SYNOPSIS セクションにおいて、セクション 2 または 3 の関数の説明で使われます。‘
.Fd
’マクロから他のマクロを呼び出すことはなく、他のマクロから呼び出すこともできません。
使い方: .Fd include_file (or defined variable)
SYNOPSIS セクションにおいて、関数がすでに示されていて改行が入っていない場合、‘ .Fd
’によって改行が挿入されます。これによって前の関数呼び出しと次の関数の宣言の間に最適な行間が設定されます。
フラグ
‘.Fl
’マクロはコマンド行のフラグを扱います。フラグの前にはダッシュ‘
-
’が挿入されます。対話的なコマンドのフラグでは、ダッシュがフラグの前には挿入されませんが、‘
.Cm
’ (コマンド修飾子) マクロは、ダッシュを付けないことを除き、同じ働きをします。
使い方: .Fl argument ... [.,:;()[]?!]
-
.Fl
- -
-
.Fl cfv
- -cfv
-
.Fl cfv .
- -cfv.
-
.Fl s v t
- -s -v -t
-
.Fl - ,
- --,
-
.Fl xyz ) ,
- -xyz),
引数なしで‘ .Fl
’マクロを指定すると、標準入力/標準出力を意味するダッシュとなります。ひとつのダッシュに‘ .Fl
’マクロを使用すると、 2 つダッシュとなることに注意して下さい。‘ .Fl
’マクロは解析され、呼び出し可能です。
関数 (ライブラリルーチン)
‘.Fn
’マクロは ANSI C の記法を規範としています。
使い方: .Fn [type] function [[type] parameters ... [ .,:;()[]?! ]]
-
.Fn getchar
- getchar()
-
.Fn strlen ) ,
- strlen()),
-
.Fn "int align""const * char *sptrs"
, - 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
’と‘ .Fc
’マクロは解析され、呼び出し可能です。 SYNOPSIS セクションでは、関数は常に行の先頭から開始されます。 SYNOPSIS セクションにおいて、複数の関数が示されており、関数の型が示されない場合、改行が挿入され、現在の関数名とその前の関数名の間に最適な改行量が設定されます。現在、‘ .Fn
’は troff の行の長さに対して、語の境界をチェックしておらず、予期しない場所で改行が挿入されてしまうことがあります。これは近い将来修正されるでしょう。
関数の型
このマクロは SYNOPSIS セクションで使うものです。 man ページ中の他の場所でも問題なく使うことができますが、セクション 2 と 3 の SYNOPSIS セクションでカーネルの通常の形式で関数の型を示すことがこのマクロの目的です (このマクロは関数名が次の行に置かれるように改行を挿入します)。
使い方: .Ft type ... [.,:;()[]?!]
-
.Ft struct stat
- struct stat
‘ .Ft
’は他のマクロからは呼び出せません。
対話的なコマンド
‘.Ic
’マクロは対話的なコマンド、もしくは内部コマンドを指定します。
使い方: .Ic argument ... [.,:;()[]?!]
-
.Ic :wq
- :wq
-
.Ic do while {...}
- do while {...}
-
.Ic setenv , unsetenv
- setenv, unsetenv
‘ .Ic
’を引数なしで呼び出すのはエラーです。‘ .Ic
’マクロは解析され、呼び出し可能です。
名前マクロ
‘.Nm
’マクロは文書のタイトルやサブジェクト名を指定するために使われます。このマクロは最初に呼び出された時の引数を覚えておくという特性を持っており、それは常にそのページのサブジェクト名であるべきです。引数なしで呼び出されると‘
.Nm
’は作者の作業を少なくするためだけの目的で、最初の名称を出力します。注意: セクション 2 または 3 のドキュメントの関数名は
NAME セクションにおいて‘
.Nm
’で指定され、
SYNOPSIS セクションや残りのセクションでは‘
.Fn
’で指定されます。
csh(1) での‘
while
’コマンドのキーワードのような対話的なコマンドでは‘
.Ic
’マクロを使うべきです。‘
.Ic
’はほとんど‘
.Nm
’と同一ですが、それが最初に使われたときの引数を記憶することはできません。
使い方: .Nm argument ... [.,:;()[]?!]
-
.Nm mdoc.sample
- mdoc.sample
-
.Nm \-mdoc
- -mdoc.
-
.Nm foo ) ) ,
- foo) ),
-
.Nm
- mdoc.samples
‘ .Nm
’マクロは解析され、呼び出し可能です。
オプション
‘.Op
’マクロはコマンド行の残りのすべての引数をオプションであることを示す角括弧で囲み、末尾の句読点は角括弧の外に置きます。‘
.Oc
’マクロと‘
.Oo
’マクロは複数行に渡って使うことができます。
使い方: .Op options ... [.,:;()[]?!]
-
.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]
‘ .Oc
’マクロと‘ .Oo
’マクロ:
.Oo .Op Fl k Ar kilobytes .Op Fl i Ar interval .Op Fl c Ar count .Oc
生成結果: [ [ -k kilobytes][ -i interval][ -c count]]
‘ .Op
’と‘ .Oc
’と‘ .Oo
’マクロは解析され、呼び出し可能です。
パス名
‘.Pa
’マクロはパス名もしくはファイル名をフォーマットします。
使い方: .Pa pathname [.,:;()[]?!]
-
.Pa /usr/share
- /usr/share
-
.Pa /tmp/fooXXXXX ) .
- /tmp/fooXXXXX).
‘ .Pa
’マクロは解析され、呼び出し可能です。
変数
一般的な変数への参照です。
使い方: .Va variable ... [.,:;()[]?!]
-
.Va count
- count
-
.Va settimer
, - settimer,
-
.Va int *prt ) :
- int *prt):
-
.Va char s ] ) ) ,
- char s] )),
‘ .Va
’を引数なしで呼び出すのはエラーです。‘ .Va
’マクロは解析され、呼び出し可能です。
一般テキスト領域
AT&T マクロ
使い方: .At [v6 | v7 | 32v | V.1 | V.4] ... [ .,:;()[]?! ]
-
.At
- AT&T UNIX
-
.At v6 .
- Version 6 AT&T UNIX.
‘ .At
’マクロは解析 されず 、呼び出し 不可 です。最大 2 つまでの引数を取ることができます。
BSD マクロ
使い方: .Bx [Version/release] ... [.,:;()[]?!]
-
.Bx
- BSD
-
.Bx 4.3 .
- 4.3BSD.
‘ .Bx
’マクロは解析され、呼び出し可能です。
FreeBSD マクロ
使い方: .Fx Version.release ... [ .,:;()[]?! ]
-
.Fx 2.2 .
- FreeBSD 2.2.
‘ .Fx
’マクロは解析 されず 、呼び出し 不可 です。最大 2 つまでの引数を取ることができます。
UNIX マクロ
使い方: .Ux ... [.,:;()[]?!]
-
.Ux
- UNIX
‘ .Ux
’マクロは解析され、呼び出し可能です。
囲い/クォートマクロ
囲いの概念はクォートと似たものです。 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 文字列 | ||
.Qc | .Qo | まっすぐな二重引用符 | 文字列 | |
.Sq | .Sc | .So | 一重引用符 | `文字列' |
下記の不正なマクロを除き、すべてのクォートマクロは解析され、呼び出し可能です。句読点がひとつずつ置かれていて、スペースで区切られていれば、すべてのクォートマクロは句読点を適切に扱います。クォートマクロは開く句読点、閉じる句読点(訳注: 句読点には括弧なども含みます) を調べ、それが囲む文字列より前か後かを決めます。これによって、ある程度の入れ子が可能になっています。
-
.Ec
,.Eo
- これらのマクロは各々開始および終了の文字列を最初の引数に取ります。
-
.Ql
- リテラルをクォートするマクロは troff では nroff と異なった処理を行ないます。 nroff でフォーマットされた場合、クォート指定されたリテラルは常にクォートされます。 troff でフォーマットされた場合は、アイテムの幅が固定幅文字 3 つ分より狭い場合にのみクォートされます。これはリテラル (固定幅) のフォントの変更があまり気づかれないものであるため、短い文字列を良く見えるようにするためです。
-
.Pf
-
プレフィックスマクロは呼び出し可能ではありませんが、解析されます。
-
.Pf ( Fa name2
- は ( name2 となります。
‘
.Ns
’ (空白なし) マクロはサフィックス機能と同様の作用があります。 -
クォートの例:
-
.Aq
- <>
-
.Aq Ar ctype.h ) ,
- < ctype.h>),
-
.Bq
- []
-
.Bq Em Greek , French .
- [ Greek, French].
-
.Dq
- “”
-
.Dq string abc .
- “string abc”.
-
.Dq ´^[A-Z]´
- “´^[A-Z]´”
-
.Ql man mdoc
-
‘
man mdoc
’ -
.Qq
- “”
-
.Qq string ) ,
- “string”),
-
.Qq string Ns ),
- “string),”
-
.Sq
- ‘’
-
.Sq string
- ‘string’
囲いマクロの入れ子についての良い例については、オプションマクロ‘ .Op
’を参照してください。このマクロは上でリストされているような囲いマクロと同じベースの上に作られています。拡張引数リストマクロ‘ .Xo
’と‘ .Xc
’もまた同じルーチンをベースに作られており、 -mdoc マクロの使い方の非常に良い例となっています。
no-op もしくは通常テキストマクロ
‘.No
’マクロはマクロコマンド行において、コンテントマクロの構文形式に従うが、フォーマットされては
ならない 単語をハックするものです。
空白なしマクロ
‘.Ns
’マクロはマクロ間での不要な空白を除去します。これはフラグと引数の間に空白を含まない古いスタイルの引数リストを使う場合に便利です。
-
.Op Fl I Ns Ar directory
- は[ -Idirectory]という結果になります。
注: ‘ .Ns
’マクロは他のマクロ名が続かなければ、スペースを除去したあとに‘ .No
’マクロを常に起動します。‘ .Ns
’マクロは解析され、呼び出し可能です。
相互参照と引用
以下のマクロは多少なりとも参考文献を扱えるようにと意図したものです。これらのマクロは、せいぜい参照スタイルの参考文献のサブセットを手動で作成しやすくする程度です。
-
.Rs
- 参考文献の開始。改行を挿入してから、参考文献の終了マクロが読み込まれるまで参考文献の情報を収集する。
-
.Re
- 参考文献の終了。参考文献が表示される。
-
.%A
- 参考文献の作者名。1 回の呼び出しにつき、作者名をひとつ指定する。
-
.%B
- 書籍のタイトル。
-
.%C
- 都市/場所。
-
.%D
- 日付。
-
.%J
- 定期刊行物の名称。
-
.%N
- 発行番号。
-
.%O
- 追加の情報。
-
.%P
- ページ番号。
-
.%R
- 報告書の名称。
-
.%T
- 記事のタイトル。
-
.%V
- 巻数。
‘ %
’で始まるマクロは呼び出し不可能ですが、呼び出し側に戻る商標名マクロだけは解析されます。 (現時点では予期できないことです。) 商標名のみ解析されるのは troff/ ditroff の出力をきれいにするためです。
返り値
‘.Rv
’マクロは
RETURN VALUE のセクションで使うテキストを生成します。
使い方: .Rv [-std function]
‘ .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 のマニュアルページでのみ有効です。
商標名 (頭文字とタイプ名)
商標名マクロは一般的に長さが 2 文字を越えるすべてが大文字の単語用に使われる小さな大文字のマクロです。
使い方: .Tn symbol ... [.,:;()[]?!]
-
.Tn DEC
- DEC
-
.Tn ASCII
- ASCII
‘ .Tn
’マクロは解析され、他のマクロから呼び出し可能です。
拡張引数
‘.Xo
’と‘
.Xc
’マクロでマクロの境界における引数リストを拡張することができます。引数リストは‘
.Op
’のようなすべての引数が 1 行中に指定されていることを前提としているマクロの中では行に渡って拡張することができません。
以下に空白モードマクロをスペーシングをオフにするために使った‘ .Xo
’での例を示します。
.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]
囲いマクロを使った‘ .Xo
’の他の例: 変数の値をテストして下さい。
.It Xo .Ic .ifndef .Oo \&! Oc Ns Ar variable .Op Ar operator variable ... .Xc
これは以下のような結果になります。
- .ifndef [ !] variable [ operator variable ...]
上のすべての例では‘ .It
’ (リスト項目) マクロの引数リストに‘ .Xo
’マクロを使用しています。拡張マクロが使われることはあまりありません。使われるとすれば、リスト項目の引数リストを拡張する場合です。残念なことに、これが拡張マクロが最も懲り性であるところでもあります。最初の 2 つの例では、スペーシングはオフになっています。3 番目では、ある箇所にはスペーシングを入れることが望ましいのですが、出力全体に入れたいわけではありません。そのような状況でこれらのマクロが適切に動作するためには、‘ .Xo
’と‘ .Xc
’マクロが 3 番目の例にあるように指定されていることを確認してください。‘ .Xo
’マクロが置かれた‘ .It
’の引数リストに他のものが置かれると、スペーシングがどうなるかは予測不可能です。この場合、‘ .Ns
’ (空白なしマクロ) は行中の最初もしくは最後のマクロに指定してはいけません。現在 BSD でリリースされている 900 のマニュアルページ (実際のページでは約 1500 ページ) のうち 15 のマニュアルページでのみしか‘ .Xo
’が使われていません。
ページ構造のドメイン
セクションヘッダ
以下にリストされている、最初の 3 つのセクションヘッダマクロ‘.Sh
’はすべての man ページで必須のものです。残りのセクションヘッダはマニュアルページの作者の裁量において、推奨されているものです。‘
.Sh
’マクロは 9 つまでの引数を取ることができます。これは解析されますが、呼び出し不可能です。
- .Sh 名前
-
名前 (NAME) マクロは必須のものです。これが指定されていないと、ヘッダとフッタ、それにデフォルトのページレイアウトが設定されず、結果はかなり好ましくないものになるでしょう。
NAME セクションは最低 3 つの項目からなります。最初のものは名称マクロ‘
.Nm
’であり、man ページのサブジェクトとなります。2 番目のものは名称説明マクロ‘.Nd
’であり、サブジェクト名を 3 つめの項目、すなわちその名称の説明と分離します。説明に割り当てられるスペースは小さいものですので、できるだけ簡潔で分かりやすいものでなければなりません。 - .Sh 書式
-
書式 (SYNOPSIS) セクションはその man ページのサブジェクトとなっている項目の典型的な使用法を説明します。必須のマクロは‘
.Nm
’, ‘.Cd
’, ‘.Fn
’のいずれかです。 (他には‘.Fo
’, ‘.Fc
’, ‘.Fd
’, ‘.Ft
’のマクロも必要な場合があります。) 関数名マクロ‘.Fn
’はセクション 2 と 3 のマニュアルページにおいて必須のもので、コマンドと一般名称マクロ‘.Nm
’はセクション 1, 5, 6, 7, 8 で必須の項目です。セクション 4 のマニュアルでは‘.Nm
’か‘.Fd
’、もしくはコンフィギュレーションデバイス使用法マクロ‘.Cd
’が必要です。その他のいくつかのマクロが下に示すような書式行を生成するために必要なことがあります。
以下のマクロが使われています。
.Nm cat
.Op Fl benstuv
.Op Fl
.Ar
注: マクロ‘ .Op
’, ‘ .Fl
’, ‘ .Ar
’はパイプの文字‘ |
’を認識し、下記のようなコマンド行
.Op Fl a | Fl b
はうまくいきません。 troff は通常 | を特別のオペレータとして解釈します。この他で | が使える場合については 定義済みの文字列 セクションを参照して下さい。
- .Sh 説明
-
説明 (DESCRIPTION) セクションでの最初のテキストは、ほとんどの場合ではそのコマンド、関数もしくはファイルについての短い段落で、オプションの構文リストとそれぞれの説明がそれに続きます。そのようなリストを作成するにはリスト開始マクロ‘
.Bl
’、リスト項目マクロ‘.It
’、リスト終了マクロ‘.El
’を使います (後述の リストと列 セクションを参照)。
以下の‘ .Sh
’のセクションヘッダはマニュアルページの好ましいレイアウトの一部であり、一貫性を保つために適切に使われなければなりません。これらは使われる順番にリストされています。
- .Sh 環境変数
- 環境変数 (ENVIRONMENT) セクションは関連する環境変数を明らかにし、それらの振舞いや使用方法を示します。
- .Sh 例
- 使用例、実行例を作成するには様々な方法があります。詳細については、下の 例 のセクションを参照してください。
- .Sh ファイル
-
man ページのサブジェクトによって使用されるか生成されるファイルで、
ファイル のセクション中でマクロ‘
.Pa
’によってリストされます。 - .Sh 関連項目
-
関連項目 (SEE ALSO) セクションには、その man ページの題材に関する資料への参照と他の関連する man ページへのクロスリファレンスが記載されます。クロスリファレンスは‘
.Xr
’マクロによって指定されます。 関連項目 セクションでのクロスリファレンスはセクション番号順に並べ、セクション中ではカンマで区切ってアルファベット順に並べなければなりません。以下に例を示します。ls(1), ps(1), group(5), passwd(5).
ここで参考スタイルである refer(1) は適応されていません。
- .Sh 準拠
- コマンドやライブラリ関数やファイルが、 IEEE Std 1003.2 (“POSIX.2”) や ANSI X3.159-1989 (“ANSI C89”) のような特定の実装によるものであれば、ここで記述します。コマンドがどの規格にも基づいていなければ、その歴史は 歴史 (HISTORY)のセクションで説明されなければなりません。
- .Sh 歴史
- 特定の規格に基づいていないコマンドは、このセクションでその歴史の概要が説明されるべきです。
- .Sh 作者
- クレジットが必要であれば、ここで入れます。
- .Sh 診断
- コマンドからの診断はこのセクションに入れます。
- .Sh エラー
-
特定のエラーハンドリング、特にライブラリ関数 (man ページのセクション 2, 3, 9) でのエラーハンドリングは、ここで説明します。‘
.Er
’マクロが errno を記述するために使われます。 - .Sh バグ
- あきらかな問題はここで記述します...
ユーザ指定の‘ .Sh
’セクションを追加することができます。たとえば、このセクションは以下のように設定されています。
.Sh ページ構造領域
段落と行スペース
- .Pp
-
‘
.Pp
’段落コマンドは必要な場合に行スペースを指定するために使われます。このマクロは、‘.Sh
’マクロや‘.Ss
’マクロの後や、‘.Bl
’マクロの前では必要ありません。 ( ‘.Bl
’マクロは -compact フラグが指定されていなければ、縦方向の距離を宣言します)。
キープ
現在実装されているキープは単語に対するものだけです。それらは‘.Bk
’ (キープ開始) マクロと‘
.Ek
’ (キープ終了) マクロです。‘
.Bk
’に指定できるオプションは
-words のみであり、これはオプションの途中で改行が入らないようにするのに便利です。コマンド行の引数を生成する例 (
この名前には何が...? セクションを参照) において、キープは
nroff がフラグと引数を別の行に分けないように使われています。 (実際には、オプションマクロがこの目的で使われていましたが、オプションが行中にわたって散らばってしまうと一般的に見栄えが悪くなるという理由により
troff で右揃えのマージンを強制的に行なう (宗教的な) 決定がなされてから、オプションマクロをこの目的で使わないようになりました。キープマクロについてはもっと機能を向上する作業が必要であり、
-line オプションを追加していく必要があります。)
例やディスプレイ
ディスプレイには 5 つのタイプがあります。即席 1 行インデントディスプレイ‘.D1
’、即席 1 行リテラルディスプレイ‘
.Dl
’、それにディスプレイ開始マクロ‘
.Bd
’とディスプレイ終了マクロ‘
.Ed
’を使用するリテラルブロック、フィルブロックおよび凸凹ブロックです。
-
.D1
-
(D-いち) インデントされたテキストを 1 行表示します。このマクロは解析されますが、呼び出し不可能です。
-ldghfstru
これは次の指定で生成されます:
.Dl
-ldghfstru -
.Dl
-
(D-エル) インデントされた
リテラル テキストを 1 行表示します。‘
.Dl
’マクロの例は本ファイルの中に渡って使われています。これによって 1 行のテキストのインデント (表示) が可能になります。このマクロは解析され、他のマクロを認識することができますが、デフォルトのフォントは固定幅 (リテラル) にセットされています。しかしながら、呼び出しは不可能です。% ls -ldg /usr/local/bin
これは次の指定で生成されます:
.Dl % ls -ldg /usr/local/bin
. -
.Bd
-
ディスプレイ開始です。‘
.Bd
’によるディスプレイは‘.Ed
’マクロによって終了しなければなりません。ディスプレイはディスプレイ内およびリスト内で入れ子にすることができます。‘.Bd
’は以下の書式をとります。.Bd ディスプレイタイプ [-offset オフセット値] [-compact]
ディスプレイタイプは以下の 4 つのタイプの内の 1 つでなければならず、インデント‘
.Bd
’のオフセット値を指定することができます。
- -ragged
- テキストのブロックをタイプされた通りに表示します。右マージン (と左マージン) のエッジは左に不揃いに寄せられます。
- -filled
- フィル (フォーマット) されたブロックを表示します。テキストのブロックがフォーマットされます (エッジは左非揃えではなく、フィルされます)。
- -literal
- リテラルなブロックを表示します。ソースコードや、単純にタブもしくはスペースで整えられたテキストで便利です。
- -file ファイル名
- -file フラグに続く名称のファイルが読み込まれ、表示されます。表示はリテラルなモードで行われ、タブは定幅文字 8 つ分に固定されますが、ファイル中のすべての troff/ -mdoc コマンドは解釈されます。
- -offset string
-
-offset が以下の文字列のいずれかとともに指定されていると、その文字列は次のテキストのブロックのインデントのレベルを示すものとして解釈されます。
- left
-
ブロックを現在の左マージンに揃えます。これは‘
.Bd
’のデフォルトのモードです。 - center
- ブロックを中央揃えにします。残念ながら現時点では、単にブロックの左側を仮想的な中央マージンに揃えるだけです。
- indent
-
デフォルトのインデント値もしくはタブの分だけインデントします。デフォルトのインデント値はディスプレイ‘
.D1
’でも使われ、これら 2 つのタイプのディスプレイを使った場合、行が揃うことが保証されています。このインデントは通常 6n か約 2/3 インチ (定幅文字 6 つ分) です。 - indent-two
- デフォルトのインデント値の 2 倍分インデントします。
- right
- これはブロックをページの右端から約 2 インチ離して 左 揃えします。このマクロはちゃんと動作する必要があるのですが、 troff ではまったくちゃんと動作してくれていません。
- .Ed
- ディスプレイ終了。
フォントモード
マニュアルページのテキストの見栄えを変更するマクロは 5 つあります。- .Em
-
テキストは‘
.Em
’マクロで強調することができます。強調の場合、通常イタリック体のフォントが使われます。使い方: .Em argument ... [.,:;()[]?!]
-
.Em does not
- does not
-
.Em exceed 1024 .
- exceed 1024.
-
.Em vide infra ) ) ,
- vide infra) ),
‘
.Em
’マクロは解析され、呼び出し可能です。‘.Em
’を引数なしで呼び出すのはエラーです。 -
- .Li
-
リテラルマクロ‘
.Li
’は特殊文字や変数定数、その他タイプされた通りに表示する必要があるものに使用することができます。使い方: .Li argument ... [.,:;()[]?!]
-
.Li \en
-
\n
-
.Li M1 M2 M3 ;
-
M1 M2 M3
; -
.Li cntrl-D ) ,
-
cntrl-D
), -
.Li 1024 ...
-
1024 ...
‘
.Li
’マクロは解析され、呼び出し可能です。 -
- .Sy
-
シンボリック体強調マクロはシンボリックの意味でも伝統的な英語の使いかたにおいても、通常はボールドマクロとなっています。
使い方: .Sy symbol ... [.,:;()[]?!]
-
.Sy Important Notice
-
Important Notice
‘
.Sy
’マクロは解析され、呼び出し可能です。‘.Sy
’の引数は引用符で囲むことができます。
-
-
.Bf
-
フォントモード開始。フォントモード‘
.Bf
’は‘.Ef
’マクロで終了しなければなりません。フォントモードは他のフォントモードと入れ子にすることができます。‘.Bf
’は次の構文を取ります。.Bf font-mode
font-mode は以下の 3 つのタイプのうちのいずれかでなければなりません。
- Em | -emphasis
-
強調モード。‘
.Em
’マクロがテキストブロック全体に使われているのと同様です。 - Li | -literal
-
リテラルモード。‘
.Li
’マクロがテキストブロック全体に使われているのと同様です。 - Sy | -symbolic
-
シンボリックモード。‘
.Sy
’マクロがテキストブロック全体に使われているのと同様です。
- .Ef
- フォントモードの終了。
タグ付きリストと列
リスト開始マクロ‘.Bl
’で開始されるリストにはいくつかのタイプがあります。リスト中の項目は項目マクロ‘
.It
’で指定され、各リストは‘
.El
’マクロで終了しなければなりません。リストはリスト自身やディスプレイの中で入れ子にすることができます。列はリストの中で使うことができますが、リストが列の中で使えるかどうかは検証されていません。
さらに、タグの幅、リストのオフセット、コンパクトさ(項目間の空白行が許されているかどうか) のような、いくつかのリストの属性を指定することができます。本ドキュメントのほとんどはタグ ( -tag) スタイルリストでフォーマットされています。各種リストタイプは、調子を変えるためにオーバーハング ( -ohang) でリストしました。このリストのタイプは TeX のユーザに非常に人気のあるものですが、 tag リストで構成されたページを何ページも読んだ後には幾分変に見えるでしょう。以下のリストタイプを‘ .Bl
’で使うことができます。
- -bullet
- -item
- -enum
-
これら 3 つは最も単純なリストのタイプです。一旦‘
.Bl
’マクロが与えられると、リスト中の項目は単に‘.It
’マクロによってのみ構成される行で指定されます。例として、簡単な列挙リストのソーステキストは、このようになります。.Bl -enum -compact .It ひとつめはここ。 .It そしてふたつめ。 .It 最後にみっつめはここ。 .El
これらの結果は以下のようになります。
- ひとつめはここ。
- そしてふたつめ。
- 最後にみっつめはここ。
簡単な bullet リスト構成の例を示します。
.Bl -bullet -compact .It ひとつめの bullet。 .It これはふたつめの bullet。 .El
これは以下のような結果になります。
- ひとつめの bullet。
- これはふたつめの bullet。
- -tag
- -diag
- -hang
- -ohang
- -inset
-
これらのリストタイプは‘
.It
’マクロによって指定されている引数からラベルを生成します。そして、 inset では、次のテキストへそのラベルを挿入します。 hang では、次のテキストをラベルの位置へインデントします。 ohang (オーバーハング) では、次のテキストをラベルの位置にぶら下げ、インデントしません。 tag では、タグつきテキストの形式にします。ちなみに上のリストは‘Fl ohang
’リストタイプで構成されています。‘.It
’マクロは 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 Fl
-
そのフラグでのデフォルトの幅を指定します。すべての呼び出し可能なマクロは各々デフォルトの幅の値を持っています。現在、‘
.Fl
’の値は定幅文字 10 個分、もしくは約 5/6 インチとなっています。 - -width 24n
-
定幅文字 24 個分の幅、もしくは約 2 インチの幅をセットします。これが正しく動作するには‘
n
’が必ず必要となります。 - -width ENAMETOOLONG
- 指定された文字列の固定長に幅をセットします。
- -width "int mkfifo"
- これも、指定された文字列の固定長に幅をセットします。
タグつきリストタイプで幅が指定されていないと、‘ .It
’が最初に起動された時に適した幅を決定することが試みられます。‘ .It
’の最初の引数が呼び出し可能なマクロであれば、そのマクロのデフォルトの幅がそのマクロ名が幅として指定されたように使用されます。しかしながら、そのリスト中に他の項目が別の呼び出し可能なマクロ名で与えられていると、新しく入れ子となったリストとして処理されます。
定義済みの文字列
以下の文字列はあらかじめ定義されているものであり、troff の文字列解釈シーケンス‘\*(xx
’もしくは‘
\*x
’を前に伴って使われます。ここで、
xx もしくは
x は定義されている文字列の名称です。解釈シーケンスはテキストのどこでも使うことができます。
文字列 | Nroff | Troff |
<= |
<= | ≤ |
>= |
>= | ≥ |
Rq |
'' | ” |
Lq |
`` | “ |
ua |
^ | ↑ |
aa |
' | ´ |
ga |
` | ` |
q |
" | " |
Pi |
pi | pi |
Ne |
!= | ≠ |
Le |
<= | ≤ |
Ge |
>= | ≥ |
Lt |
< | > |
Gt |
> | < |
Pm |
+- | ± |
If |
infinity | infinity |
Na |
NaN | NaN |
Ba |
| | | |
注: ‘ q
’の名称がつけられている文字列は、 1 文字であるため‘ \*q
’と書かなければなりません。
診断
-mdoc は限られたデバッグ機能しか持っていませんが、引数名と内部レジスタやマクロ名との衝突のような潜在的なエラーを検出するのに役立ちます。 (A って何?) レジスタは troff での演算用記憶クラスであり、 1 文字か 2 文字の名称がついています。 troff と ditroff での -mdoc のすべての内部レジスタは‘Ar
’のように2 文字からなる <大文字><小文字>の形式か、‘
aR
’のように <小文字><大文字>の形式か、‘
C1
’のように <大文字もしくは小文字><数字>の形式を取ります。さらに混乱することに、
troff はそれ自身の内部レジスタを持ち、それらすべては小文字 2 文字か、ドットに文字もしくはメタ文字が続く形式を取ります。紹介例の 1 つに、エスケープシーケンス‘
\&
’でマクロ名を解釈させない方法がありました。これは内部レジスタ名にも有効です。
エスケープされていないレジスタ名が引数リストに指定されると、予期できない振舞いとなります。一般的には、テキストのかなり大きな部分が出力されるべきところに出力されないとか、リストのタグのような小さな文字列が消えてしまうとか、引数リストの中の引数のタイプが間違って解釈されるとかいうことが、起こり得ます。きっとあなたのお母さんは、あなたにこんな面倒なことを覚えるようにとは考えていないでしょう。そこで、与えられた引数が有効か無効かを判断する方法があります。
そんなときには、‘ .Db
’ (デバッグ) マクロによってほとんどのマクロの引数リストがどう解釈されるかを表示することができます。‘ .Pp
’ (段落) マクロのようなマクロはデバッグ情報を含んでいません。呼び出し可能なマクロはすべてデバッグ情報を含んでおり、疑いがある場合はいつでも‘ .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
この情報の最初の行では呼び出されているマクロの名称が出力されています。ここでは‘ .Op
’とそれが現れた行番号が表示されています。複数のファイルが処理されている場合 (特にテキストが他のファイルからインクルードされている場合)、行番号は正しくないでしょう。ファイルが 1 つだけの場合には正しい行番号が出力されます。 2 番目の行では引数の個数と引数 (‘ Fl
’) とその長さが出力されています。引数の長さが 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 で改ページ時に通常挿入されるヘッダとフッタは禁止されており、マニュアルをオンラインで効率良く見ることができるようになっています。現在の所、 -Tascii が指定された 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 ページのいくつかの例
バグ
フラグ引き数のダッシュが意図せずハイフンにより折り返しになるバグはまだ修正されておらず、 DESCRIPTION セクションでときどき意図しない動作 (ハイフンでの改行) が起こることがある。あらかじめ定義されている文字列は文書において宣言されていません。
セクション 3f はヘッダルーチンには追加されていません。
‘ .Nm
’フォントは 名前 セクションにおいて変更されるべきです。
‘ .Fn
’は分割されるのを防止するために、行の長さが短すぎないかどうかをチェックする必要があります。ときどき、最後の括弧が分割されることがあり、行がフィルモードであるときには全くおかしな結果になることがあります。
nroff 使用時に、(最初のヘッダとフッタ以外の) 改ページ時のヘッダとフッタの挿入を行わないようにするのに使用される命令によって、ときどき見るに耐えない部分的な行詰め (や空行) がページの末尾に発生する場合がある。
リストマクロとディスプレイマクロはキープを行いませんが、これはキープを行うべきです。
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.51 の一部である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。December 30, 1993 | FreeBSD |