THE LINUX MAN-PAGE-HOWTO <author>Jens Schweikhardt<schweikh@noc.dfn.de> <date>April 1996 <trans>北山公一 <kitayama@dimgrey.av.sanyo.co.jp> <tdate>30 May 1996 <abstract>この HOWTO は、man(1) コマンドから利用したいオンラインドキュメント -- いわゆる man page -- を書こうとするときに、注意すべき事柄について説明する。</abstract> <toc> <verb> Copyright 1995,96 by Jens Schweikhardt <schweikh@noc.dfn.de> 配布に関する条件については、下記を参照最終変更: １９９６年４月訂正及び提案を歓迎する。 </verb> この HOWTO は、man(1) コマンドから利用したいオンラインドキュメント -- いわゆる man page -- を書こうとするときに、注意すべき事柄について説明する。この HOWTO を通じて、manual entry のことを実際のページ数に関わらず、 [a] man page と略称する。また、この略称は、性差別主義に基づくものでもない。 <sect> ドキュメンテーションについての若干の考察 なぜドキュメンテーションを書くのか？　馬鹿げた質問かもしれない。もちろん、他の人達が、我々が造ったプログラムや、ライブラリ関数、その他のものを使うことができるようにするためである。しかし、ドキュメンテーションを書くということには、それ以上のものがある。 <descrip> <tag/＋ドキュメンテーションはアクセスできなければならない。/ドキュメンテーションに関連するツールが探すことのできない標準的ではない場所に隠されているなら、目的を達成することができない。 <tag/＋ドキュメンテーションは、正確で、信頼のおけるものでなければならない。/ プログラムの動作とドキュメンテーションの記述が一致しないことほど、うっとうしいことはない。ユーザーはあなたを罵り、うらみつらみのメールを送り、こんな間抜けが書いたものなど、２度とインストールしないと決意をして、あなたのプログラムを削除してしまうだろう。 </descrip> UNIX において歴史が有り、良く知られたドキュメンテーションの方法は、 man(1) コマンドを利用するものである。この HOWTO は、ドキュメンテーションに関連するツールによって正しく処理されるために何をすべきかについて説明する。ドキュメンテーションに関連するツールとして重要なものには、 man(1)、xman(1x)、apropos(1) 、makewhatis(8) 、catman(8) がある。 情報の正確さと信頼性は、もちろん、書き手であるあなた次第である。しかし、以下の文章は、この観点においても、参考になるだろうし、よくある過ちを避ける手助けになるだろう。 <sect>man page はいかにしてアクセスされるか？ 作成する man page に正しい名称を与え、正しい場所にインストールするためには、man page がどのようにアクセスされるかについての正確な仕組みを知ることが必要である。man page はすべて、特定のセクションに所属しており、このセクションは１文字で表されている。Linux での標準のセクションとその意味は次の通り。 <verb> セクション名前 1 だれもが実行できるユーザコマンド 2 システムコール、つまり、カーネルが提供する関数　 3 サブルーチン、つまり、ライブラリ関数 4 デバイス、つまり、/dev ディレクトリのスペシャルファイル 5 ファイルフォーマットの説明、例 /etc/passwd 6 ゲーム（説明不要だろうネ） 7 その他例：　マクロパッケージや取り決め的な文書 8 システム管理者だけが実行できるシステム管理用のツール 9 Linux 独自のカーネルルーチン用のドキュメンテーション n 新しいドキュメンテーション：よりふさわしい場所に移動されるだろう o 古いドキュメンテーション　猶予期間として保存されているもの l 独自のシステムについてのローカルなドキュメンテーション </verb> man page のためのソースファイル（フォーマットシステムへの入力）の名前は、対応するコマンド、関数もしくはファイルの名前で始まり、それにドットとセクション名が続く。例えば、passwd のファイルのフォーマットについてのドキュメンテーションを書く場合、ソースファイルの名称は、passwd.5 としなければならない。この場合は、コマンドの名称とファイルの名称が同じ例である。また、passwd という名称のライブラリサブルーチンがあるかもしれない。セクションの設定は、これらの曖昧さを解決するために通常利用される方法である。すなわち、コマンドについての説明は、passwd.1 のファイルに、例としてあげたライブラリサブルーチンの説明は、passwd.3 のファイルに書かれることになる。 <quote> 時折、いくつかの文字が追加されて、例えば、 xterm.1x とか wish.1tk というファイル名となることがある。これの意味するところは、夫々が、Ｘウィンドウ又はＴｋのアプリケーションに対するドキュメンテーションであることを明らかにすることである。マニュアルのブラウザによっては、この追加の情報を利用できる。例えば、xman は、利用可能なドキュメンテーションのリスト中に、xterm(x) や wish(tk) を使用する。 n や o 及び l のセクションを使わないで欲しい。ファイルシステムスタンダードでは、これらのセクションは非難されている。数字のセクションを忠実に使って欲しい。 </quote> 既に存在するプログラム、関数又はファイルとの名前の衝突に注意すべきである。独自のエディタを作ってこれを ed とか sed （改良された(smart な） ed の意味で）、red （ロッキーの ed ）と命名することはよくない考えだ。作成するプログラムの名称が固有であることを確実にすることで、あなたの作ったプログラムをだれかが実行して、別のだれかのプログラムの man page を読んだり又はその逆の事態を避けることができる。プログラムの名称についての lsm データベースを、ますチェックすべきだ。 さて、作成するプログラムの名称が決まった。次にするべきことは、どのディレクトリにこのプログラムがインストールされるかを決めるということである。言い換えれば、ユーザーが make install を実行したときにインストールされるディレクトリのこと。Linux では、全ての man page は、環境変数 MANPATH で指定されたディレクトリにある。ドキュメンテーションに関連するツールは環境変数 MANPATH を、シェルが環境変数 PATH を利用するのと同様に利用する。実際、MANPATH は、PATH と同じフォーマットである。どちらも、コロンで分けられたディレクトリのリストを含んでいる（MANPATH では、空のフィールドが認められていないし、相対パス名ではなく絶対パス名だけが利用できるという違いはあるが）。環境変数 MANPATH が設定されていなければ、少なくとも /usr/man ディレクトリを含んだデフォルトの設定が使用される。検索の速度を上げ、占有するディレクトリを小さくするために、MANPATH で指定されたディレクトリ（ベースディレクトリと呼ばれる）には、man<s> という名のサブディレクトリが作成されている。ここで、<s> は先に説明したテーブルでのセクションを表す一文字である。全てのセクションに対応するサブディレクトリが設けられている訳ではない。これは、空の mano サブディレクトリを残しておく必要がないと言う単純な理由からである。しかし、別に、 cat<s> とか dvi<s> とか ps<s> という名のディレクトリ（表示、印刷の準備が出来ているドキュメンテーションを備えた）があるかもしれない。これらについては、後で詳しく説明する。ベースディレクトリにある他のファイルは、whatis ファイルだけである。このファイルの目的とこのファイルの作成についても 12 節で説明する。セクション <s> に所属する man page を正しい場所にインストールする一番安全な方法は、 <tt>/usr/man/man<s></tt> のディレクトリに置くことである。しかし、よい Makefile は、例えば、make 変数 MANDIR を用いて、ユーザーにベースディレクトリを選択できるようにしている。多くの GNU パッケージではディレクトリを指定できるプレフィクスオプションを利用して設定できる。 <tt>prefix=/what/ever</tt> としたとき、ベースディレクトリとして <tt>/what/ever/man</tt> に、マニュアルがインストールされる。私が薦めるのは、同じ様な方法を用意することである。 <quote> Linux ファイルシステム標準 (FS-Stnd) の出現により、事態はさらに複雑になった。FS-Stnd 1.2 では、「/usr/man の構造において、異なる言語（複数の言語）で書かれた manual page をサポートする約束を決める必要がある」とされている。これは、異なる言語の間で区別される別のディレクトリレベルを導入することで達成される。再び FS-Stnd 1.2 を引用すると： 「usr/man の言語によるサブディレクトリの命名は、POSIX 1003.1 標準の補遺 E （ロケール識別文字列について説明している）に基づく。すなわち、文化の異なる環境を記述するのに最も受け入れられている方法である。「ロケール」文字列は： </quote> <verb> <言語>[_<地域>][.<文字セット>][,<バージョン>] </verb> <quote> （幾つかの共通のロケール文字列については、FS-Stnd を参照のこと） このガイドラインによれば、man page のディレクトリは <tt>/usr/man/<locale>/man[1-9lno]</tt> となる。フォーマットされたドキュメントは、 <tt>/usr/man/<locale>/cat[1-9lno]</tt> におかれるべきだ。こうしないと、フォーマットされたドキュメントは、一種類のロケールにだけしか準備できないことになる。 しかし、私としては、現時点でこのようなディレクトリ構成に切換えることは薦めない。FS-Stnd 1.2 でも「全ての man page についてコードセットと言語が統一されているなら、<locale> 文字列を省略して <mandir> にすべての manual page を保存してもよい」と許されている。例えば、英語だけの ASCII コードの manual page のシステムでは、<tt>/usr/man</tt> ディレクトリの man[1-9] のディレクトリに manual page がおかれることになるだろう。（これは、実際、伝統的な環境である） 私は、全てのツール、例えば、xman, tkman, info その他の man page を利用するツールが、新しいディレクトリ構造に対応するまで、切換はしないつもりである。 </quote> <sect>フォーマットされた man page はどのようにあるべきか？ まず、一つの例をあげて、その後、詳しく説明することにする。この文書の性質から、いくつものフォント（ボールドとかイタリック）を表示することはできない。より詳しい説明は、「フォントに関する取り決め」を参照して欲しい。 以下が、架空のプログラム foo についての man page である。 <tscreen><verb> FOO(1) User Manuals FOO(1) 名称 foo - bar ライブラリを調整する。形式 foo [-bar] [-c config-file ] file ... 説明 foo は、内部のシンボルテーブルをチューンアップして、bar ライブラリを調整する。デフォルトでは、全ての baz セグメントをパースして、xyzzy(1) リンカが検索できるように、時間の逆順に並び変える。symdef のエントリは、WBG (Whiz-Bang-Gizmo：ヒューズドン法) のアルゴリズムを利用して圧縮される。全てのファイルは、与えられた順に処理される。オプション -b 処理中に、標準出力に `busy' を出力しない。 -c config-file 指定されたファイル config-file をシステム全般に関わる設定ファイルとして、デフォルトの設定ファイル /etc/foo.conf の代わりに使用する。環境変数 FOOCONF に優先する。 -a baz セグメントに加えて、blurfl ヘッダもパースする。 -r 再帰処理モード。大量の仮想メモリを使って超高速に処理を行なう。ファイル /etc/foo.conf システム全般に関わる設定ファイル。詳細は、foo(5)を参照。 ~/.foorc ユーザー毎の設定ファイル。詳細は、foo(5)を参照。環境変数 FOOCONF システム全般に関わる別の設定ファイル foo.conf へのパス名を設定。-c オプションが優先する。診断メッセージ標準エラー出力に、以下の診断メッセージが表示される。悪いマジックナンバー入力ファイルが、書庫ファイルではない。 baz セグメントのフォーマットが古い foo は新しいフォーマットの baz セグメントのみを処理できる。現在のバージョンでは、COBOL のオブジェクトライブラリを処理できない。バグコマンド名は、ちゃんとコマンドの目的がわかるようなものにすべきである。作者 Jens Schweikhardt <jens@kssun3.rus.uni-stuttgart.de> 関連項目 bar(1), foo(5), xyzzy(1) Linux MARCH 1995 1 </verb></tscreen> さて、約束の説明をしよう。 <descrip> <tag/名称セクション/ 名称のセクションは、必須のセクションである。名前のセクションがなければ Man page は、北極点での冷蔵庫なみの価値しかない。名前セクションは、カンマで区切られたプログラムや関数のリストとダッシュ(-) に続く説明（通常は１行）、つまり、プログラムや関数、ファイルが果たす機能の短い説明が含まれれた標準化された形式を持つ。makewhatis(8) は、名前セクションを利用して whatis データベースファイルを作成する。makewhatis が利用するので、名前セクションが必須であり、形式が標準化されているのである。groff のソースでは、次のようにならないといけない。 <verb> .SH 名称 foo \- bar ライブラリを調整する。 </verb> ここで、\- は重要である。バックスラッシュはダッシュをコマンド名や一行説明にでてくるハイフォネーションのダッシュと区別するために必要である。 <tag/形式セクション/ 形式セクションは、指定できるオプションの簡単な説明が含まれる。関数の場合、その関数を含むインクルードファイルとプロトタイプ宣言が記載され、プログラマは、引数の型や数、関数の返り値の型を知ることが出来る。 <tag/ 説明セクション/ 説明セクションでは、この０と１のデータの並びつまりプログラムに一体全体どんな価値があるかについて、詳しい説明が記載される。あなたが書く場合、あなたの持てる知識全部を書くようにする。いわば、名声の殿堂なのだ。他のプログラマやユーザの称賛を得るためには、詳しくて信頼のおける記載にしなければならない。どの引数が何のためにあり、どのようなファイルフォーマットが用いられ、どのようなアルゴリズムが、プログラムの処理に用いられているかを説明しなければならない。 <tag/オプションセクション/ オプションのセクションでは、オプションがプログラムの動作に与える影響について説明される。自分のプログラムだから、オプションについてはよく知ってるよね？ <tag/ファイルセクション/ ファイルのセクションでは、プログラムまたは関数が使用するファイルを列挙する。例えば、設定ファイル、初期ファイル、プログラムが直接操作するファイルなどのこと。これらのファイルのフルパス名を記載し、ユーザの好みに合わせてインストールするディレクトリを変更できるインストール処理を作ることはいい考えである。例えば、groff のマニュアルでは、デフォルトのプレフィクスは <tt>/usr/local</tt> であり、通常、 <tt>/usr/local/lib/groff/*</tt> のファイルを参照する。しかし、'make prefix=/opt/gnu' と実行してインストールすると、man page での参照は、 <tt>/opt/gnu/lib/groff/＊</tt> のファイルに対するように変更される。 <tag/環境変数セクション/ 環境変数のセクションでは、プログラムや関数に関する環境変数全てが列挙され、もちろん、どう影響するかの説明がある。普通、環境変数により、パス名やファイル名、デフォルトのオプションが指定される。 <tag/診断メッセージセクション/ 診断メッセージセクションには、プログラムからのよくあるエラーメッセージの簡単な説明とエラーメッセージに基づきどうすべきかについて記載すべきだ。プログラムを実行した時に表示されるかも知れない、システムエラーメッセージ（perror(3) からのもの）とか、致命的なシグナル（psignal(3) からのもの）については、説明する必要はない。 <tag/バグセクション/ バグセクションは、理想を言えば、ないほうが良い。勇気があるなら、プログラムの制限とか、わかっているプログラムの不便なところ、他の人がおかしいとみなす機能について、書けば良い。勇気がなければ、"将来の予定" （TO DO）とでも名前を変えよう ;-) <tag/著者のセクション/ プログラムの動作とかドキュメントにエラーがいっぱいあって、バグレポートを送って欲しいのなら、著者のセクションを設けることは良い考えだが... <tag/関連項目セクション/ 関連項目のセクションは、関連する man page のアルファベット順のリストであり、慣習的に、最後におかれる。 </descrip> 上に説明したセクションに合わない内容については、別のセクションをつくり出しても構わない。 では、正確には、どのようにして man page のソースを書けば良いのだろうか？そう来ると、思っていたよ、ルーク。ソースファイルは次のようになる。 <verb> .\" このソースファイルを次のように処理すること。 .\" groff -man -Tascii foo.1 .\" .TH FOO 1 "MARCH 1995" Linux "User Manuals" .SH 名称 foo \- bar ライブラリを調整する。 .SH 形式 .B foo [-bar] [-c .I config-file .B ] .I file .B ... .SH 説明 .B foo は、内部シンボルテーブルをチューンアップして、bar ライブラリを調整する。デフォルトでは、全ての baz セグメントをパースして、 .BR xyzzy (1) リンカが検索できるように、時間軸で逆順に並べ変える。 symdef エントリは、WGB（Whiz-Bang-Gizmo：ヒューズドン法）のアルゴリズムを用いて圧縮される。全てのファイルは与えられた順に処理される。 .SH オプション .IP -b 処理中に、標準出力に `busy' を出力しない。 .IP "-c config-file" 指定されたファイル .I config-file をシステム全体に関連する設定ファイルとして、デフォルトの設定ファイル .IR /etc/foo.conf . の代わりに使用する。環境変数 .B FOOCONF に優先する。 .IP -a baz セグメントに加えて、blurfl ヘッダもパースする。 .IP -r 再帰処理モード。大量の仮想メモリを使って、超高速で処理を行なう。 .SH ファイル .I /etc/foo.conf .RS システム全般に関わる設定ファイル。詳細は .BR foo (5) を参照。 .RE .I ~/.foorc .RS ユーザー毎の設定ファイル。詳細は .BR foo (5) を参照。 .SH 環境変数 .IP FOOCONF システム全般に関わる設定ファイル .IR foo.conf へのフルパス名を設定。 .B -c オプションが優先する。 .SH 診断メッセージ標準エラー出力に、以下のエラーメッセージが表示される。悪いマジックナンバー .RS 入力ファイルが、書庫ファイルではない。 .RE baz セグメントのフォーマットが古い .RS .B foo は新しいフォーマットの baz セグメントのみを処理できる。現在のバージョンでは、COBOLのオブジェクトライブラリを、処理できない .SH バグコマンド名は、ちゃんとコマンドの目的がわかるようなものにすべきである。 .SH 著者 Jens Schweikhardt <jens@kssun3.rus.uni-stuttgart.de> .SH "関連項目" .BR bar (1), .BR foo (5), .BR xyzzy (1) </verb> <sect>どうすれば、複数のプログラムや関数を一つの man page にまとめることができるか？ 多くのプログラム（例えば grep, egrep）や関数(例えば、printf, fprintf,...）は、単独の man page 中に説明が記載されている。しかし、これらの man page が一つの名称だけで参照できるだけなら、全く不便だろう。使用者が、egrep の man page が、実際は grep の man page であると覚えていてくれることは、期待できないのだ。従い、この man page は、複数の名称で利用できるようにすることが必要になる。実現する方法には次のものがある。 <enum> <item>それぞれの名称に対してファイルのコピーを用意する。 <item>ハードリンクで全ての man page をリンクする。 <item>実際の man page をシンボリックリンクで指定する。 <item>groff の .so マクロによるソース機能を利用する。 </enum> 最初の方法は明らかにディスクの無駄である。次は、catman プログラムの改良バージョンでは、ファイルタイプや内容を探すのに多くの処理を省くことができるので、お勧めできない。ハードリンクは、catman プログラムの賢い処理を妨げるだろう。（catman の目的は全ての man page をフォーマットして、より早く表示できるようにすることである。）３番目の方法は、少し欠点がある。柔軟性が重要な場合、シンボリックリンクをサポートしないファイルシステムがあると言うことを念頭におかなければならない。結局、最上の方法は、 groff のソースメカニズムを利用することである。つまり、次のようにする。 man page を foo と bar という名前でセクション１で、アクセス可能にしようとする時、この man page を foo.1 に記載して、bar.1 に次の行を書き込む。 <verb> .so man1/foo.1 </verb> 重要なことは、ディレクトリ名「man1/」をファイル名 foo.1 と共に指定することである。これは、groff がブラウザから実行された時、先に述べた man page の標準ディレクトリをカレント・ワーキング・ディレクトリ（cwd）とするからで、groff は、この cwd に対して「.so」の引数を解釈するからである。 <sect>どのマクロパッケージを使うべきか？ man page を書く時に利用することを目的としたいくつかのマクロがある。通常は、これらのマクロは、groff マクロディレクトリである /usr/lib/groff/tmac におかれる。ファイル名は、tmac.<なんとか> で、<なんとか> は groff の -m オプションの引数である。Groff は `-m <なんとか >' オプションが指定された時に、マクロファイル tmac.<なんとか> を使用する。しばしば、`-m' と`<なんとか>' の間のスペースが省略され、tmac.an のマクロパッケージを利用して man page をフォーマットする時に、`groff - man' を使うことになる。これが、`tmac.an' というおかしな名前を持っている理由である。 tmac.an 以外に、tmac.doc という、これも良く利用されるマクロパッケージがあり、これは、カリフォルニア大学のバークレー分校（UCB）でもともと開発されたものである。多くの BSD の man page はこれを使用しており、UCB は、これをドキュメンテーションの標準にしているようである。tmac.doc は、非常に柔軟であるけれども、悲しいかな、tmac.doc を使わないで、常に、 `groff -man' を呼び出すマニュアルブラウザがある。例えば、私が今まで見た全ての xman プログラムは、tmac.doc を要求する man page を台無しにしてしまう。したがって、tmac.an を使うことにしてほしい。他のマクロパッケージを使用することは、有害であると考えられる。Tmac.andoc は、類似のマクロパッケージであって、ソースを見て、tmac.an か tmac.doc を読み込む。本当は、全ての man page ブラウザは、tmac.andoc を使用すべきなんだろうけど、今までのところそうではなく、最良の方法は、古めかしい tmac.an にしがみついてる他ない。そこで、ここからは、tmac.an にだけについて説明することにする。 <quote> もし、tmac.doc マクロを使いたいと言うことなら、以下のポインタを参照してほしい。 </quote> <verb> http://www.bsdi.com/bsdi-man </verb> <quote> そこには、検索可能なインデックスがある。'mdoc' と入力すれば、mdoc(7)、 mdoc.samples(7) 及びBSD man page を書くためのチュートリアルが得られる。 </quote> <sect>どのプリプロセッサが使えるのか？ Groff は少なくとも、tbl、eqn 及び pic の３つのプリプロセッサを使用する。（名称は、gtbl、geqn 及び gpic の場合がある）。これらのプリプロセッサの目的は、プリプロセッサマクロを解釈し、データを通常の troff の入力に変換することにある。Tbl は表のプリプロセッサ、eqn は方程式／数学用のプリプロセッサ、pic は図形用のプリプロセッサである。それぞれの機能についての詳細は、man page を参照してほしい。 簡単にいうなら、man page は、プリプロセッサを必要としない様に書くこと。 Eqn プリプロセッサは、man page を利用するうちの９９％を占めるタイプライタのようなデバイスに対しては、全くひどい出力を出す。例えば、 XAllocColor.3x は累乗表記を含んだ数式を用いている。タイプライタの様なデバイスなので、指数は、基数と同じライン上に並ぶ。つまり、 N の２乗が `N2' の様に表示される。 Tbl ブリプロセッサは、使うのを避けるべきである。というのは、私の見た限り、xman プログラムは、Tbl プリプロセッサの処理に失敗しているからだ。Xman 3.1.6 は、signal(7) を例にとれば、man page をフォーマットするのに、次のコマンドを用いる。 <tscreen><verb> gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man \ > /tmp/xmana01760 2> /dev/null </verb></tscreen> このコマンドは、gtbl プリプロセッサを用いることで、ソースを台無しにしてしまう。というのは、gtbl プリプロセッサの出力が、もう一度 gtbl プリプロセッサで処理されるからだ。処理結果は、あなたが意図したテーブルが、なくなってしまった man pege ということになる。これが、バグなのか、gtbl プリプロセッサが自身の出力を窒息させる仕様なのか、それとも xman が gtbl プリプロセッサを２回も使わないようにされるべきなのかは、私にはわからない。いずれにしろ、テーブル（表）を使いたいのなら、自分でフォーマットしておいて、.nf と .fi で挟み、フォーマットされないようにしよう。この方法では、ボールド、イタリックが使えないが、表がなくなってしまうようなことはない。 Pic プリプロセッサを必要とする man page については、見たことがない。しかし、私自身は、好ましくないと思う。上に例示したように、xman は pic プリプロセッサを使わないし、groff はやっぱり入力をめちゃくちゃにしてしまうだろう。 <sect>配布すべきはソースかフォーマットされたドキュメンテーションか？ いくつかの選択枝の中から、長所（＋）と短所（－）を挙げてみよう。 <enum> <item>ソースのみ：<verb> ＋パッケージのサイズが小さい－ groff のないシステムでは、利用できない </verb> <item>圧縮されていないフォーマット済ファイルのみ：<verb> ＋ groff がなくても利用できる－ dvi ファイルや postscript ファイルを生成できない。－圧縮された man page を取り扱うシステムにとっては、ディスクスペースの無駄 </verb> <item>圧縮されたフォーマット済ファイルのみ：<verb> ＋ grof がなくても利用できる－ dvi ファイルや postscript ファイルを生成できない。－配布する圧縮フォーマットには何を使うかが問題。 .Z か、.z か、.gz か、それともこれらのすべてか？ </verb> <item>ソースと圧縮されていないフォーマット済ファイル：<verb> ＋ grof がなくても利用できる－配布パッケージのサイズが大きくなる－いくつかのシステムでは、フォーマットされた man page は、圧縮されていることを前提としている。－ groff のために準備される余分な情報 </verb> </enum> 私の見解を言わせてもらえるのなら、ソースのみの配布が最上の方法である。 Groff のないシステムで利用で来ないという問題は重要でない。５００以上ある Linux ドキュメンテーションプロジェクトでの man page は、ソースのみの配布である。XFree86 の man page はソースのみの配布である。FSF からの man page もソースのみである。実際、私は、フォーマットされた man page がソフトウェアと一緒に配布されたのをみたことがない。システム管理者が、本当に man page を利用可能にしようとしているのなら、groff もまた、インストールされているだろう。 <sect>フォントに関する取り決めとは？ 第一に、\fB や \fP のような直接のフォントオペレータを使わないこと。引数を指定するマクロを用いる方が良い。この方法なら、よくある不都合、つまり、範囲の終端で、フォントの変更を忘れて、次のフォントの変更の部分まで、ボールドやイタリックが延長される不都合を避けることが出来る。嘘だと思うだろうが、実際、良くあることなのだ。 Tmac.an マクロでは、以下のタイプフェイスが使える。 <verb> .B ボールド .BI ボールドとイタリックが交互 .BR ボールドとローマンが交互 .I イタリック .IB イタリックとボールドが交互 .IR イタリックとローマンが交互 .RB ローマンとボールドが交互 .RI ローマンとイタリックが交互 .SM 小さめのサイズ（標準の９／１０のサイズ） .SB 小さくてボールド（小さめのサイズとボールドが交互になるのとは違う） </verb> 「X と Y が交互」というのは、奇数番目の引数のタイプセットが、X となり、偶数番目の引数のタイプセットが Y になることである。例えば、 <verb> .BI "引数１はボールド " "引数２はイタリック " "ボールド " "そしてイタリック" </verb> ここで、引数に空白を含めるためには、ダブルクォーテーションマークが必要である。 使えるものはこれくらいである。さて、次に、いろいろなタイプフェイスの使い方を決めなければならない。（部分的に man(7) をそのまま引用してしまった） UNIX の世界では、man page についての多くの気難しいしきたりがあるけれども、Linux 独自の数百の man page が、我々の標準である。 関数については、引数は常に、形式のセクションにおいても、イタリックを使い、関数の他の部分は、ボールドを使う。つまり、 <verb> .BI "myfunction(int " argc ", char **" argv ); </verb> ファイル名は、形式セクションを除いて、常にイタリックで表す。形式セクションではインクルードされるファイルには、ボールドを使う。つまり、次のようにする。 <verb> .I /usr/include/stdio.h and .B #include <stdio.h> </verb> 特別のマクロ（普通大文字で表記される）には、ボールドを使う。 <verb> .B MAXINT </verb> エラーコードを列挙する時には、コードをボールドにする。このリストは、普通、.TP （ぶら下がりタグを伴った段落）マクロを次のように用いる。 <verb> .TP .B EBADF .I fd は、有効なファイル識別子ではない。 .TP .B EINVAL .I fd は、読み出しに適していない。 </verb> 他の man page につての言及（もしくは現在の man page のテーマについての言及）にはボールドを使う。マニュアルのセクション番号がある時には、空白なしのローマンで表す。 <verb> .BR man (7) </verb> 短縮形を使う時は、小さい文字を使った方が、見栄えが良いので、お勧めである。 <verb> .SM UNIX .SM ASCII .SM TAB .SM NFS .SM LALR(1) </verb> <sect>いかにして man page をより良くしていくか？ 以下は、ドキュメンテーションの信頼性、可読性、見栄えを改善するためのガイドラインだ。 <verb> ＋コマンドが動作するかやってみる。この時も man page からカットアンドペーストで、man page どおり正確に、コマンドを実行し、コマンドの出力を、man page 中に、記述する。プログラムが出力するだろうと考えるものを書くのではない。＋校正、ispell によるスペルチェック、誰かに読んでもらうこと（あなたが英語を母国語としないのなら、特に必要）。実はこの HOWTO もネイティブによるチェックは、まだなのだが、誰か希望者はいないだろうか？＋書いた man page をテストする：man page をフォーマットする時に、groff がエラーを出さないか？コメントとして groff のコマンドラインを記入することは良いことだ。man(1) コマンドは、 `man <あなたの書いたプログラム名>' とやった時に、エラーを出さないだろうか？ Man(1) コマンドがフォーマットシステムを利用する方法は、期待した結果を出力するだろうか？ Xman(1x) と tkman(1tk) とは、あなたの作ったマニュアルを処理できるだろうか？ XFree86 3.1 では xman 3.1.6 - X11R6 を使うが、解凍する時に、次の処理を行なう。 gzip -c -d < %s > %s zcat < %s > %s ＋ Makewhatis(8) は、名前セクションから、一行説明を抜き出すことができるか？ </verb> <sect>＾H とか＾_ などのない man page のテキストはどうすれば得られるか？ col(1) を見よう。col はバックスペースシーケンスを取り除ける。それも面倒と言うのなら、次の様にタイプしよう。 <tscreen><verb> funnyprompt% groff -t -e -mandoc -Tascii manpage.1 | col -bx \ > manpage.txt </verb></tscreen> -t と -e のスイッチは、groff に tbl と eqn を使っての前処理を指定する。前処理を必要としない man page にとっては、過剰な指定だけれども、数 CPU サイクルの無駄にしかならない。反対に、必要な時に -t のスイッチを指定しないと、表がめちゃくちゃにフォーマットされてしまい、有害である。Man page に限らず、groff のドキュメントをフォーマットするために必要なコマンドについては、次の様にタイプすれば、わかるだろう（grog コマンドを使うから、"見当をつける" ことができるのほうがいいかな）。 <tscreen><verb> funnyprompt% grog /usr/man/man7/signal.7 groff -t -man /usr/man/man7/signal.7 </verb></tscreen> "Grog" は、"GROff Guess" から来ており、その名の通り見当をつけることをする。Grog が完全だったならば、その出力以上のオプションは必要ないんだけど。私の経験では、grog は、マクロパッケージについては、間違うが、プリプロセッサについては正しかった。 以下は、私が書いた簡単な perl のスクリプトで、ページヘッダとフッタを削除できる。これを使えば、長くて詳細な man page を印刷する時に、数ページは、得することができる。"strip-header" という名でファイルに保存して "chmod 755" として欲しい。 <verb> #!/usr/bin/perl -n # 一度にファイル全体を読み込んで： undef $/; # ページ区切りを削除し： s/\n{4}\S.{50,}\n{6}\S.{50,}\n{3}/\n/g; # 最初のヘッダと最後のフッタを削除し： s/\n\S.{50,}\n//g; # ２行以上の空行を１行にまとめて： s/\n{3,}/\n\n/g; # できあがり... print; </verb> 次のように、`man' コマンドの次の最初のフィルタとして使うこと。Groff によって出力される改行の数に、処理が依存しているから。 <tscreen><verb> funnyprompt% man bash | strip-headers | col -bx > bash.txt </verb></tscreen> <sect>高品質のポストスクリプトの man page を得るには？ <tscreen><verb> funnyprompt% groff -t -e -mandoc -Tps manpage.1 > manpage.ps </verb></tscreen> とやって、好みのポストスクリプトプリンタで印刷しよう。オプションの説明については、10 節を見ること。 <sect>apropos と whatis を利用できるようにするには？ 使っているシステムにどんなコンパイラがインストールされており、どうすれば起動できるかを知りたいとしよう。この質問（FAQだが）への答えは、次のようにすることである。 <tscreen><verb> funnyprompt% apropos compiler f77 (1) - Fortran 77 compiler gcc (1) - GNU C and C++ compiler pc (1) - Pascal compiler </verb></tscreen> Apropos と whatis は、あるトピックに関する情報がどの man page にあるかについての素早い回答を与えてくれる。どちらのプログラムもそれぞれのマニュアルのベースディレクトリにおかれた whatis と名付けられたいくつかのファイルを検索する。前に説明したように、whatis データベースファイルは、それぞれのディレクトリ中の man page に対する一行のエントリを備えている。実際には、この一行は、名前セクションのものと同じである（正確に言うなら、一行にまとめられ、ハイフォンが除かれ、セクション番号が括弧で囲まれて追加されている）。Whatis データベースファイルは、makewhatis(8) プログラムにより作成される。いくつかのバージョンがあるので、あなたの書く man page には、どのオプションが適用できるかを言及しておいてほしい。 Makewhatis プログラムが、名前セクションを正確に抜き出すためには、マニュアルの作者が、パラグラフ２で説明した名前セクションのフォーマットを守ることが大切だ。Apropos と whatis の違いは、データベース中のどこ、そして何を検索するかである。Apropos （man -k と等価である）は、一行中の引数を検索し、whatis （man -f と等価）はダッシュより前の部分のコマンド名全体と一致するものを探す。従って、`whatis cc' は cc についてのマニュアルがあれば出力を行なうが、gcc に対しては、何も出力しない。 訂正及び提案を歓迎する。 <sect>著作権について <verb> Copyright 1995,96 by Jens Schweikhardt <schweikh@noc.dfn.de> Voice: ++49 7151 909516 </verb> 他に説明がない限り、Linux HOWTO ドキュメントは、それぞれの著作者に著作権が属する。この著作権についての注意書が添付される限り、Linux HOWTO ドキュメントは部分的又は全体で、物理的又は電子的に、複製及び配布をすることが出来る。商業的な配布は、認められているし、推奨もされているが、著作者には連絡をお願いしたい。 要約すれば、我々は、可能な限り多くの手段を介して、この情報の普及を推進したい。しかし、この HOWTO ドキュメントの著作権は各著作者に残しておきたいと考え、これらの HOWTO の再配布の計画については通知を受けたいのである。 もし、疑問があるなら、Linux HOWTO コーディネータである Greg Hankins に連絡してほしい。電子メールアドレスは gregh@sunsite.unc.edu である。 [訳者より] 以下に著作権についての原文を念のため引用しておきます。 Unless otherwise stated, Linux HOWTO documents are copyrighted by their respective authors. Linux HOWTO documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions. All translations, derivative works, or aggregate works incorporating any Linux HOWTO documents must be covered under this copyright notice. That is, you may not produce a derivative work from a HOWTO and impose additional restrictions on its distribution. Exceptions to these rules may be granted under certain conditions; please contact the Linux HOWTO coordinator at the address given below. In short, we wish to promote dissemination of this information through as many channels as possible. However, we do wish to retain copyright on the HOWTO documents, and would like to be notified of any plans to redistribute the HOWTOs. If you have questions, please contact Greg Hankins, the Linux HOWTO coordinator, at gregh@sunsite.unc.edu via email. 訳についてのコメント等は北山 <kitayama＠dimgrey.av.sanyo.co.jp> まで、お願いします。 最後になりましたがこの MANPAGE HOWTO の翻訳には、JF-ML での他の皆さんのいろいろなやりとりを参考にさせて頂きました。また、東芝の甲斐さんには、直接にアドバイスを頂きました。この場でお礼申し上げます。 </article>