Rechercher une page de manuel
man
Langue: ja
Version: 2007-05-17 (mandriva - 01/05/08)
Section: 7 (Divers)
Sommaire
名前
man - man ページを整形するマクロ書式
groff -Tascii -man file ...groff -Tps -man file ...
man [section] title
説明
このマニュアルページでは、 groff tmac.an のマクロパッケージ (しばしば man マクロパッケージとも呼ばれることも多い) とマニュアルページ (man page) を 作成する際の決まり事について説明する。このマクロパッケージは、 Linux の man ページを書いたり移植したりするときに、 開発者が用いるものである。 このマクロパッケージはバージョン間での互換性が高く、 man page の移植にあたっては大きな問題はないだろう (但し、NET-2 BSD release は例外である。 こちらでは mdoc と呼ばれる全く異なるマクロパッケージが使用されている。 mdoc(7) を参照)。NET-2 BSD の man ページも、 groff のオプションとして -man の代わりに -mdoc を指定するだけで、利用することができる。 -mandoc オプションを使えばどのマクロパッケージが用いられているか 自動的に検出できるので、このオプションを使うのがお薦めである。
プリアンブル (preample)
man ページの (コメント行を除く) 最初のコマンドは、 以下のようにする必要がある。 コメント行とは .\" で始まる行のことである。
.TH title section date source manual,
-
- title
- man ページのタイトル。全部大文字で記載する (例: MAN)。
- section
- man ページが属するセクション番号 (例: 7)。
- date
- 最新のリビジョンの日付 --- man ページに変更を加えたときには 必ずこれを変更すること。 これが最も一般的なバージョン管理方法である。 日付は YYYY-MM-DD の形式で記載すべきである。
- source
- コマンド、関数、システムコールの出自。
バイナリには次のようなものを用いる: GNU, NET-2, SLS Distribution, MCC Distribution.
システムコールの場合、単に Linux とだけ書く。 (以前の慣習では、マニュアルページを記載した/内容を確認したカーネルの バージョン番号を記載していた。しかし、バージョン番号が実際の内容と 一致していることはなく、そのためバージョン番号がないよりも おそらく悪い形になっていた。 今後は、バージョン番号を含めるのは避けること。)
ライブラリコールには関数の出自を用いる: GNU, 4.3BSD, Linux DLL 4.4.1.
- manual
- マニュアルのタイトル (例: man-pages パッケージのセクション 2 および 3 のページの場合には、 Linux Programmer's Manual を使うこと)。
なお BSD の mdoc フォーマットのページは TH コマンドではなく Dd コマンドから始まる。
マニュアルのセクションは、習慣的に以下のような定義が用いられている:
-
- 1 コマンド (プログラム)
- シェルの中からユーザが実行できるコマンド。
- 2 システムコール
- カーネルが処理しなければならない関数。
- 3 ライブラリコール
- libc の関数の大部分。
- 4 スペシャルファイル (デバイス)
- /dev 以下にあるファイル。
- 5 ファイルのフォーマットと規約
- /etc/passwd などの人間に可読であるファイルのフォーマット。
- 6 ゲーム
- 7 約束事その他
- 様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。
- 8 システム管理コマンド
- mount(8) のような root のみが実行可能なコマンド。
セクション
セクションは .SH で始まり、見出し名がそれに続く。 昔から使われてきたセクション名を以下のリストに示す。 これらを使うと良いだろう。 一般的に、マニュアルページは、少なくとも「色つき」の セクションを持つのが望ましい。 新しくマニュアルページを作成する際には、だいたい以下のリストに示した 順序でセクションを配置するようにしてもらいたい。名前 書式 説明 オプション [通常はセクション 1, 8 のみ] 環境変数 ファイル バージョン [通常はセクション 2, 3 のみ] 返り値 [通常はセクション 2, 3 のみ] 終了ステータス [通常はセクション 1, 8 のみ] エラー [たいていはセクション 2, 3 のみ] 準拠 注意/備考 バグ 例 関連項目これらの見出し名のどれかが適用できる場合は、それを使ってほしい。 この種の一貫性を保つことで、情報を理解しやすくなるからである。 ただし、もっと理解しやすくなるような場合には、 どんどん新しい見出し名を作ってほしい。
NAME (名前) という見出しだけは必ず置かないといけない。 この見出しは一番最初のセクションにすべきで、見出しの 次の行にはプログラムの説明を一行で書く。
.SH NAME
chess \- the game of chess
良く用いられる他のセクションと、そこに書く内容とをいくつか示す:
- 書式 (SYNOPSIS)
- コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。 そのまま書くテキストにはボールド体を用い、置き換える引き数には イタリックを用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...) を書く。 関数に対しては、必要なデータ宣言や #include 指定を書き、関数宣言を続ける。
- 説明 (DESCRIPTION)
- プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 オプション のセクションを用いる。
- 返り値 (RETURN VALUE)
- ライブラリルーチンが呼び出し元に返す値のリストを与える。 それらの値が返された場合の状態に対する説明も書く。
- 終了ステータス (EXIT STATUS)
- プログラムの終了ステータスの値と、それらの値に対応する状況をリストする このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
- オプション (OPTIONS)
- プログラムが受け付けるコマンドライン・オプションと、 その場合プログラムの振舞いがどう変わるかを説明する。 このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
- 例 (EXAMPLE)
- この関数・ファイル・コマンドをどのように使うかを示した ひとつまたは複数の例を記述する。
- ファイル (FILES)
- プログラムや関数が用いるファイルを列記する。 例えば、設定ファイル、起動ファイル、プログラムが直接操作するファイルなどである。 これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。 多くのプログラムではデフォルトのインストール先は /usr/local である。したがってベースとなるマニュアルページでも /usr/local が使われていることが多いだろう。
- 環境変数 (ENVIRONMENT)
- プログラムや関数に影響する環境変数をリストし、それらの効果を書く。
- バージョン (VERSIONS)
- システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。
- 準拠 (CONFORMING TO)
- 説明対象が実装している標準や規格を書く。
- 注意 (NOTES)
- その他の注意点を書く。
- バグ (BUGS)
- 制限・知られている欠陥や不便な点、その他不思議な動作などを書く。
- 著者 (AUTHOR)
- 文書またはプログラムの著者を列記し、 バグレポートをメールで送ることができるようにする。 「著者セクションの使用は推奨できない」 (例外はセクション 4 のページのデバイスドライバの作者のリストであり、 これはソフトウェアのバグを作者に連絡できるようにするためである)。 一般的には、著者のリストを各ページに撒き散らさない方がよい (時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅に修正を行った場合には、 ソースファイルにコメントとして著作権表示を追加すること。
- 関連項目 (SEE ALSO)
- 関連する man ページをアルファベット順にリストする。 可能なら関連する他の文書も書く。 慣習では、このセクションは最後に置く。
フォント
UNIXの世界では man ページについて勝手な慣習がたくさんあるが、 数百ある Linux 特有の man ページでは、以下のような標準が用いられている:- 関数に対しては、引き数には常にイタリックを用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」 関数の他の部分はボールドを指定する:
- int myfunction(int argc, char **argv);
- ファイル名は常にイタリックにする (例: /usr/include/stdio.h), ただし書式 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: #include <stdio.h>)。 通常、大文字で表現する特殊マクロはボールドで表す (e.g., MAXINT).
- エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 .TP マクロを用いる).
- そのマニュアルページの説明対象への参照は、ボールドで名前を記載し、 その後ろにローマンフォント (通常のフォント) で丸括弧の対を続ける (例: man())。 マニュアルページのソースファイルには次のように記載するのが望ましい:
-
.BR man ()
("\fB...\fP()" よりも、この形式を使うこと。 これにより、マニュアルページのソースファイルを解釈するツールを 書くのが簡単になる。) - 別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必ず」書く。セクション番号は ローマンフォント (通常のフォント) で書き、スペースは入れない (例: intro(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい:
-
.BR intro (2)
相互参照にセクション番号を含めておくと、 man2html といったツールがページ間のハイパーリンクを適切に生成できる。)
タイプフェイスを選択するコマンドは以下のように指定する:
- .B
- ボールド。
- .BI
- ボールドとイタリックとを交互に (特に関数指定に便利)。
- .BR
- ボールドとローマンとを交互に (特に他のマニュアルページを参照するときに便利)。
- .I
- イタリック。
- .IB
- イタリックとボールドとを交互に。
- .IR
- イタリックとローマンとを交互に。
- .RB
- ローマンとボールドとを交互に。
- .RI
- ローマンとイタリックとを交互に。
- .SB
- スモールとボールドを交互に。
- .SM
- スモール (頭字語などに用いる)
慣例としては、各コマンドは 6 つまでの引き数を持つ事が可能だが、 GNU の実装では制限はないようだ (しかし移植性を保持するためには 引き数は 6 までに限っておくのが良いだろう)。 引き数はスペースで区切られる。 スペースを含んだ引き数を与えるには、ダブルクォートで囲えばよい。 すべての引き数はスペースを取り除いて並べられるので、 .BR コマンドを使えば、単語はボールドで、句読点をローマンで表すことができる。 引き数が全く与えられなければ、 そのコマンドは次の行のテキストに適用される。
その他のマクロや文字列
以下に、他のマクロや定義済みの文字列を示す。 特に記述がない限り、マクロを使うと改行が行われる (テキストの現在の行を終了する)。 多くのマクロは 「優先インデント (prevailing indent)」を設定したり、使用する。 優先インデントの値は、どのマクロからもパラメータ i によって指定できる (以下に示す)。 マクロでは i を省略することもでき、その場合は現在の優先インデントの値が用いられる。 これにより結果として、インデントされた段落が連続している場合、 インデントの値を再指定しなくてもインデント量を同じにすることができる。 通常の (インデントされていない) 段落が登場すると、 優先インデントの値はデフォルトの値 (0.5 インチ) にリセットされる。 デフォルトでは、与えたインデントの値は ens 単位である。 インデントの単位には ens や ems を用いるとよい。これらの単位は フォントサイズが変更されると自動的に調整されるからである。 他の重要なマクロ定義は以下の通り:
通常の段落
- .LP
- .PP と同じ (新たな段落の開始)。
- .P
- .PP と同じ (新たな段落の開始)。
- .PP
- 新しい段落を開始し、インデントをリセットする。
相対マージンインデント
- .RS i
- 相対マージンインデント (relative margin indent) を開始する。 左マージンを i だけ右に移動する (i が省略されると優先インデントの値が用いられる)。 新たな優先インデントは 0.5 インチにセットされる。 結果として、以下の段落は対応する .RE が現れるまでインデントされる。
- .RE
- 相対マージンインデントを終了し、 優先インデントの値を元に戻す。
段落をインデントするマクロ
- .HP i
- ぶらさがりインデントの段落を開始する (段落の先頭行は通常の段落の左マージンとなり、 段落の残りの行はインデントされる)。
- .IP x i
- インデントされた段落。オプションとしてぶらさがりタグをとる。 タグ x が省略されると、以下の段落すべてが i でインデントされる。タグ x が与えられると、タグはインデントされた段落の前にぶら下げられる (.TP とちょうど同じ。ただしタグを次の行に書く代わりにコマンドに指定する)。 タグが長すぎる場合には、タグに続くテキストは次の行に移動する (テキストが失われたり混ざったりすることはない)。 箇条書きをするには、 \(bu (点) あるいは \(em (ダッシュ) をタグにしてこのマクロを用いるとよい。番号付きで箇条書きをする場合は、 数字または文字にピリオドを付けたものをタグにすればよい。 こうすれば他のフォーマットへの変換が簡単になる。
- .TP i
- ぶらさがりタグの段落を開始する。タグは次の行に指定する。 結果は .IP コマンドと似たものになる。
ハイパーテキストリンク用のマクロ
(groff だけでサポートされている機能) ハイパーテキストリンク用のマクロを使用するためには、 www.tmac マクロパッケージをロードする必要がある。 ロードを行うには .mso www.tmac リクエストを使用する。- .URL link url trailer
- URI (URL) url へのハイパーテキストリンクを挿入する。 link はリンク名のテキストであり、 trailer の内容はリンクの直後に表示される。 HTML を生成する時に、このマクロは <A HREF="url">link</A>trailer という HTML コマンドに変換される。
- このマクロや他の関連マクロは新しく、 多くのツールはこれらに対しては何もしないであろう。 (troff を含めた) 多くのツールは未定義のマクロを単に無視するだけ (あるいは最悪でもマクロをテキストとして挿入するだけ) なので、これらを書いても危険はない。
- マニュアルページ内で自分で URL マクロを定義して、 groff 以外の roff ビューアでも表示されるようにするのもいいだろう。 こうすることで、URL も、リンク用のテキストも、(もしあれば) それに続く テキストも、表示できるようになる。
- 以下に例を挙げる:
- .de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ...
(later in the page)
This software comes from the
.URL "http://www.gnu.org/" "GNU Project" " of the"
.URL "http://www.fsf.org/" "Free Software Foundation" .
- .de URL
- 上記の例において、 groff を使って表示しようとした場合には、 www.tmac マクロパッケージの URL マクロの定義の方が ローカルで行われた定義よりも優先される。
他にもいくつかのリンク用のマクロが用意されている。 詳しくは groff_mwww(7) を参照のこと。 .SHその他のマクロ
- .DT
- タブをデフォルトのタブ値 (0.5 インチごと) にリセットする。 改行はしない。
- .PD d
- パラグラフ間の間隔を引き数にセットする (省略されると d=0.4v となる)。
- .SS t
- サブヘッダ t (.SH のようなものだが、サブセクションのために用いる)。
定義済みの文字列
man パッケージには、以下のような定義済みの文字列がある:- \*R
- 登録シンボル: ®
- \*S
- デフォルトフォントサイズを変更する
- \*(Tm
- 商標シンボル:
- \*(lq
- 左に傾いたダブルクォート: ``
- \*(rq
- 右に傾いたダブルクォート: ''
安全なサブセット
技術的には man は troff のマクロパッケージだが、実際には多数の別のツールが man ページのファイルを処理しており、それらは troff の全ての機能を 実装していないこともある。したがって、他のツールでも正しく処理できるように、 troff のあまり一般的でない機能は、可能ならば用いないのが望ましい。 様々な troff プリプロセッサ も用いないほうが良いだろう (やむを得ない場合は tbl(1) は用いても良い。しかし 2 列の表なら、代わりに IP や TP コマンドを用いてみよう)。 計算機能も用いない方が良いだろう。他のツールのほとんどはこれらを処理できない。 他のフォーマットに変換が容易な、単純なコマンドを使うようにしよう。 以下の troff コマンドは、使っても問題ないと考えてよいだろう (多くの場合、変換コマンドによって無視されるかもしれないが)。 \ , ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, trtroff のエスケープシーケンスの多くも利用できる (これらのエスケープシーケンスは \ で始まる)。 バックスラッシュ文字を通常のテキストとして使いたい場合は \e とする。 利用できる他のシーケンスには以下のようなものがある (x や xx は任意の文字, N は任意の数字): \', \`, \-, \., \ , \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, \f(xx. グラフィックの描画にはエスケープシーケンスは用いないほうが良い。
bp (改頁) にはオプションパラメータを用いないこと。 sp (垂直スペース) には正の値のみを用いること。 man や mdoc マクロパッケージにあるマクロと、 名前が同じで機能の異なるマクロを定義 (de) しないこと。そのような再定義は無視される可能性が高い。 正方向へのインデント (in) には、負のインデントを対応させること (このマクロの代わりに RS と RE マクロを使った方がよいのだが)。 条件テスト (if,ie) は状態として 't' または 'n' だけを持つようにすること。 変換 (tr) には無視できるものだけを使うこと。 フォントの変更 (ft と \f エスケープシーケンス) には 1, 2, 3, 4, R, I, B, P, CW のみを用いること (ft コマンドの場合はパラメータを指定しなくてもよい)。
この制限を越えて機能を用いる場合は、いくつかのツールを使って、 その結果を注意してチェックすること。追加した機能が安全だと 確信したら、この文書の管理者にその安全なコマンドまたはシーケンスを 教えてほしい。リストに追加する。
ファイル
/usr/share/groff/[*/]tmac/tmac.an/usr/man/whatis
注意
テキストにはぜひとも完全な URL (または URI) を書くようにすること。 man2html(1) のようなツールは、これらを自動的にハイパーテキストリンクに変換する。 新たに取り入れられた URL マクロを関連情報へのリンクに用いても良い。 URL を書く場合は、 例えば <http://www.kernelnotes.org> のように完全な形式で書き、 ツールによる URL 自動検知ができるようにすること。
これらのファイルを処理するツールは、ファイルをオープンして 最初の空白以外の文字を調べる。行の先頭にピリオド (.) またはシングルクォート (') があると、これは troff ベースの ファイル (man や mdoc) であるとみなす。左角括弧 (<) は SGML/XML ベースのファイル (HTML や Docbook) であるとみなす。 それ以外は単純な ASCII テキスト ("catman" の結果など) とみなす。
多くの man ページは、最初の行が '\" とスペースで始まっており、 そこにはそのページが処理されるべきプリプロセスを表す文字が書いてある。 troff 以外の変換プログラムへの移植性のため、 tbl(1) や、 Linux が自動的に検知できるもの以外は使わないようにすることを勧める。 しかし、この情報を記述して、書いたページが他の (より低機能な) システムでも 扱えるようにしたい場合もあるかも知れない。 以下にこれらの文字によって起動されるプリプロセッサの定義を示す:
バグ
mdoc や DocBook に比べると、 マクロの多くは書式 (フォントタイプやスペーシングなど) に関するものであり、 意味上のもの (このテキストは他のページへの参照である、など) ではない (HTML ですら意味的なマーキングに思える)。 このため、 man フォーマットを他のメディアへ変換したり、 フォーマットを他のメディアで有効なものにしたり、 相互参照を自動的に挿入したりすることが困難になっている。 上に挙げたような安全なサブセットを守れば、 将来別のリファレンスページフォーマットへ変換する作業が簡単になるだろう。
Sun のマクロである TX は定義されていない。
関連項目
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), groff_man(7), groff_www(7), whatis(1)Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre