<!doctype linuxdoctr system>
<article>

<title>THE LINUX MAN-PAGE-HOWTO 
<author>Jens Schweikhardt&lt;schweikh@noc.dfn.de&gt; 
<date>April 1996 
<trans>北山  公一 &lt;kitayama@dimgrey.av.sanyo.co.jp&gt; 
<tdate>30 May 1996


<abstract>この HOWTO は、man(1) コマンドから利用したいオンライン
ドキュメント -- いわゆる man page -- を書こうとするときに、注意すべき事
柄について説明する。</abstract> 
<toc> 
<p>

<verb>
   Copyright 1995,96 by Jens Schweikhardt &lt;schweikh@noc.dfn.de&gt;
               配布に関する条件については、下記を参照

                     最終変更: １９９６年  ４月
                       訂正及び提案を歓迎する。
</verb>


<p>
この HOWTO は、man(1) コマンドから利用したいオンラインドキュメント -- 
いわゆる man page -- を書こうとするときに、注意すべき事柄について説明
する。

この HOWTO を通じて、manual entry のことを実際のページ数に関わらず、
&lsqb;a&rsqb; man page と略称する。また、この略称は、性差別主義に基づ
くものでもない。

<sect>
ドキュメンテーションについての若干の考察

<p>なぜドキュメンテーションを書くのか？　馬鹿げた質問かもしれない。も
ちろん、他の人達が、我々が造ったプログラムや、ライブラリ関数、その他のも
のを使うことができるようにするためである。しかし、ドキュメンテーション
を書くということには、それ以上のものがある。

<descrip>

 <tag/＋ ドキュメンテーションはアクセスできなければならない。/ドキュメ
ンテーションに関連するツールが探すことのできない標準的ではない場所に隠
されているなら、目的を達成することができない。

 <tag/＋ ドキュメンテーションは、正確で、信頼のおけるものでなければならない。/
プログラムの動作とドキュメンテーションの記述が一致しないことほど、うっ
とうしいことはない。ユーザーはあなたを罵り、うらみつらみのメールを送り、
こんな間抜けが書いたものなど、２度とインストールしないと決意をして、あ
なたのプログラムを削除してしまうだろう。
</descrip> 

UNIX において歴史が有り、良く知られたドキュメンテーションの方法は、
man(1) コマンドを利用するものである。この HOWTO は、ドキュメンテーショ
ンに関連するツールによって正しく処理されるために何をすべきかについて説
明する。ドキュメンテーションに関連するツールとして重要なものには、
man(1)、xman(1x)、apropos(1) 、makewhatis(8) 、catman(8) がある。<p>

情報の正確さと信頼性は、もちろん、書き手であるあなた次
第である。しかし、以下の文章は、この観点においても、参考になるだろうし、
よくある過ちを避ける手助けになるだろう。

<sect>man page はいかにしてアクセスされるか？
<p>
作成する 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>

<p> man page のためのソースファイル（フォーマットシステムへの入力）の
名前は、対応するコマンド、関数もしくはファイルの名前で始まり、それにドッ
トとセクション名が続く。例えば、passwd のファイルのフォーマットについ
てのドキュメンテーションを書く場合、ソースファイルの名称は、passwd.5 
としなければならない。この場合は、コマンドの名称とファイルの名称が同じ
例である。また、passwd という名称のライブラリサブルーチンがあるかもし
れない。セクションの設定は、これらの曖昧さを解決するために通常利用され
る方法である。すなわち、コマンドについての説明は、passwd.1 のファイル
に、例としてあげたライブラリサブルーチンの説明は、passwd.3 のファイル
に書かれることになる。
<quote>
<p>時折、いくつかの文字が追加されて、例えば、 
xterm.1x とか wish.1tk というファイル名となることがある。これの意味す
るところは、夫々が、Ｘウィンドウ又はＴｋのアプリケーションに対するドキュ
メンテーションであることを明らかにすることである。マニュアルのブラウザ
によっては、この追加の情報を利用できる。例えば、xman は、利用可能なド
キュメンテーションのリスト中に、xterm(x) や wish(tk) を使用する。

<p> n や o 及び l のセクションを使わないで欲しい。ファイルシステムスタ
ンダードでは、これらのセクションは非難されている。数字のセクションを忠
実に使って欲しい。
</quote>

<p>既に存在するプログラム、関数又はファイルとの名前の衝突に注意すべき
である。独自のエディタを作ってこれを ed とか sed （改良された(smart な） 
ed の意味で）、red （ロッキーの ed ）と命名することはよくない考えだ。
作成するプログラムの名称が固有であることを確実にすることで、あなたの作っ
たプログラムをだれかが実行して、別のだれかのプログラムの man page を読
んだり又はその逆の事態を避けることができる。プログラムの名称についての 
lsm データベースを、ますチェックすべきだ。

<p>
さて、作成するプログラムの名称が決まった。次にするべきことは、どのディ
レクトリにこのプログラムがインストールされるかを決めるということである。
言い換えれば、ユーザーが make install を実行したときにインストールされ
るディレクトリのこと。Linux では、全ての man page は、環境変数 MANPATH 
で指定されたディレクトリにある。ドキュメンテーションに関連するツールは
環境変数 MANPATH を、シェルが環境変数 PATH を利用するのと同様に利用す
る。実際、MANPATH は、PATH と同じフォーマットである。どちらも、コロン
で分けられたディレクトリのリストを含んでいる（MANPATH では、空のフィー
ルドが認められていないし、相対パス名ではなく絶対パス名だけが利用できる
という違いはあるが）。環境変数 MANPATH が設定されていなければ、少なく
とも /usr/man ディレクトリを含んだデフォルトの設定が使用される。検索の
速度を上げ、占有するディレクトリを小さくするために、MANPATH で指定され
たディレクトリ（ベースディレクトリと呼ばれる）には、man&lt;s&gt; とい
う名のサブディレクトリが作成されている。ここで、&lt;s&gt; は先に説明し
たテーブルでのセクションを表す一文字である。全てのセクションに対応する
サブディレクトリが設けられている訳ではない。これは、空の mano サブディ
レクトリを残しておく必要がないと言う単純な理由からである。しかし、別に、
cat&lt;s&gt; とか dvi&lt;s&gt; とか ps&lt;s&gt; という名のディレクトリ
（表示、印刷の準備が出来ているドキュメンテーションを備えた）があるかも
しれない。これらについては、後で詳しく説明する。ベースディレクトリにあ
る他のファイルは、whatis ファイルだけである。このファイルの目的とこの
ファイルの作成についても 12 節で説明する。セクション &lt;s&gt; に所属
する man page を正しい場所にインストールする一番安全な方法は、
<tt>/usr/man/man&lt;s&gt;</tt> のディレクトリに置くことである。しかし、
よい Makefile は、例えば、make 変数 MANDIR を用いて、ユーザーにベース
ディレクトリを選択できるようにしている。多くの GNU パッケージではディ
レクトリを指定できるプレフィクスオプションを利用して設定できる。
<tt>prefix=/what/ever</tt> としたとき、ベースディレクトリとして 
<tt>/what/ever/man</tt> に、マニュアルがインストールされる。私が薦める
のは、同じ様な方法を用意することである。
<p>

<quote>
Linux ファイルシステム標準 (FS-Stnd) の出現により、事態はさらに複雑に
なった。FS-Stnd 1.2 では、「/usr/man の構造において、異なる言語（複数
の言語）で書かれた manual page をサポートする約束を決める必要がある」
とされている。これは、異なる言語の間で区別される別のディレクトリレベル
を導入することで達成される。再び FS-Stnd 1.2 を引用すると：
<p>
「usr/man の言語によるサブディレクトリの命名は、POSIX 1003.1 標準の補
遺 E （ロケール識別文字列について説明している）に基づく。すなわち、文
化の異なる環境を記述するのに最も受け入れられている方法である。「ロケー
ル」文字列は：
</quote>
<verb>
       <言語>[_<地域>][.<文字セット>][,<バージョン>]
</verb>
<p>
<quote>
（幾つかの共通のロケール文字列については、FS-Stnd を参照のこと）
<p>
このガイドラインによれば、man page のディレクトリは 
<tt>/usr/man/&lt;locale&gt;/man&lsqb;1-9lno&rsqb;</tt> となる。フォー
マットされたドキュメントは、
<tt>/usr/man/&lt;locale&gt;/cat&lsqb;1-9lno&rsqb;</tt> におかれるべき
だ。こうしないと、フォーマットされたドキュメントは、一種類のロケールに
だけしか準備できないことになる。
<p>
しかし、私としては、現時点でこのようなディレクトリ構成に切換えることは
薦めない。FS-Stnd 1.2 でも「全ての man page についてコードセットと言語
が統一されているなら、&lt;locale&gt; 文字列を省略して &lt;mandir&gt; 
にすべての manual page を保存してもよい」と許されている。例えば、英語
だけの ASCII コードの manual page のシステムでは、<tt>/usr/man</tt> ディ
レクトリの man&lsqb;1-9&rsqb; のディレクトリに manual page がおかれる
ことになるだろう。（これは、実際、伝統的な環境である）
<p>
私は、全てのツール、例えば、xman, tkman, info その他の man page を利用
するツールが、新しいディレクトリ構造に対応するまで、切換はしないつもり
である。
</quote>

<sect>フォーマットされた man page はどのようにあるべきか？
<p>
まず、一つの例をあげて、その後、詳しく説明することにする。この文書の性
質から、いくつものフォント（ボールドとかイタリック）を表示することはで
きない。より詳しい説明は、「フォントに関する取り決め」を参照して欲しい。
<p>
以下が、架空のプログラム 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 &lt;jens@kssun3.rus.uni-stuttgart.de&gt;

関連項目
       bar(1), foo(5), xyzzy(1)


Linux                       MARCH 1995                          1
</verb></tscreen>

<p>
さて、約束の説明をしよう。

<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>
<p>
上に説明したセクションに合わない内容については、別のセクションをつくり
出しても構わない。
<p>
では、正確には、どのようにして man page のソースを書けば良いの
だろうか？  そう来ると、思っていたよ、ルーク。ソースファイルは
次のようになる。

<verb>
 .\" このソースファイルを次のように処理すること。
 .\" groff -man -Tascii foo.1
 .\"
 .TH FOO 1 "MARCH 1995" Linux "User Manuals"
 .SH 名称
 foo \-  bar ライブラリを調整する。
 .SH 形式
 .B foo &lsqb;-bar&rsqb; &lsqb;-c
 .I config-file
 .B &rsqb;
 .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 &lt;jens@kssun3.rus.uni-stuttgart.de&gt;
 .SH "関連項目"
 .BR bar (1),
 .BR foo (5),
 .BR xyzzy (1)
</verb>

<sect>どうすれば、複数のプログラムや関数を一つの man page にまとめることができるか？

<p>
多くのプログラム（例えば grep, egrep）や関数(例えば、printf,
fprintf,...）は、単独の man page 中に説明が記載されている。しかし、こ
れらの man page が一つの名称だけで参照できるだけなら、全く不便だろう。
使用者が、egrep の man page が、実際は grep の man page であると覚えて
いてくれることは、期待できないのだ。従い、この man page は、複数の名称
で利用できるようにすることが必要になる。実現する方法には次のものがある。

<p>
<enum>
  <item>それぞれの名称に対してファイルのコピーを用意する。
  <item>ハードリンクで全ての man page をリンクする。
  <item>実際の man page をシンボリックリンクで指定する。
  <item>groff の .so マクロによるソース機能を利用する。 
</enum>

<p>
最初の方法は明らかにディスクの無駄である。次は、catman プログラムの改
良バージョンでは、ファイルタイプや内容を探すのに多くの処理を省くことがで
きるので、お勧めできない。ハードリンクは、catman プログラムの賢い処理
を妨げるだろう。（catman の目的は全ての man page をフォーマットして、
より早く表示できるようにすることである。）３番目の方法は、少し欠点があ
る。柔軟性が重要な場合、シンボリックリンクをサポートしないファイルシス
テムがあると言うことを念頭におかなければならない。結局、最上の方法は、
groff のソースメカニズムを利用することである。

つまり、次のようにする。<p>
man page を foo と bar という名前でセクション１で、アクセス可能にしよ
うとする時、この man page を foo.1 に記載して、bar.1 に次の行を書き込
む。
<verb>
         .so man1/foo.1
</verb>

<p>
重要なことは、ディレクトリ名「man1/」をファイル名 foo.1 と共に指定する
ことである。これは、groff がブラウザから実行された時、先に述べた man
page の標準ディレクトリを カレント・ワーキング・ディレクトリ（cwd）と
するからで、groff は、この cwd に対して 「.so」の引数を解釈するからで
ある。

<sect>どのマクロパッケージを使うべきか？	
<p>
man page を書く時に利用することを目的としたいくつかのマクロがある。
通常は、これらのマクロは、groff マクロディレクトリである 
/usr/lib/groff/tmac におかれる。ファイル名は、tmac.&lt;なんとか&gt; で、&lt;な
んとか&gt; は groff の -m オプションの引数である。Groff は `-m &lt;なんとか
&gt;' オプションが指定された時に、マクロファイル tmac.&lt;なんとか&gt; を使用す
る。しばしば、`-m' と`&lt;なんとか&gt;' の間のスペースが省略され、tmac.an の
マクロパッケージを利用して man page をフォーマットする時に、`groff -
man' を使うことになる。これが、`tmac.an' というおかしな名前を持ってい
る理由である。

<p>
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 にだけについて説明する
ことにする。

<p>
<quote>
もし、tmac.doc マクロを使いたいと言うことなら、以下のポインタを参照し
てほしい。
</quote>
<verb>
           http://www.bsdi.com/bsdi-man
</verb><p>
<quote>
そこには、検索可能なインデックスがある。'mdoc' と入力すれば、mdoc(7)、
mdoc.samples(7) 及びBSD man page を書くためのチュートリアルが得られる。
</quote>
<p>



<sect>どのプリプロセッサが使えるのか？

<p>
Groff は 少なくとも、tbl、eqn 及び pic の３つのプリプロセッサを使用す
る。（名称は、gtbl、geqn 及び gpic の場合がある）。これらのプリプロセッ
サの目的は、プリプロセッサマクロを解釈し、データを通常の troff の入力
に変換することにある。Tbl は表のプリプロセッサ、eqn は方程式／数学用の
プリプロセッサ、pic は図形用のプリプロセッサである。それぞれの機能につ
いての詳細は、man page を参照してほしい。

<p>
簡単にいうなら、man page は、プリプロセッサを必要としない様に書くこと。
<p>
Eqn プリプロセッサは、man page を利用するうちの９９％を占めるタイプラ
イタのようなデバイスに対しては、全くひどい出力を出す。例えば、
XAllocColor.3x は累乗表記を含んだ数式を用いている。タイプライタの
様なデバイスなので、指数は、基数と同じライン上に並ぶ。つまり、
N の２乗が `N2' の様に表示される。

<p>
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><p>

このコマンドは、gtbl プリプロセッサを用いることで、ソースを台無しにし
てしまう。というのは、gtbl プリプロセッサの出力が、もう一度 gtbl プリ
プロセッサで処理されるからだ。処理結果は、あなたが意図したテーブルが、
なくなってしまった man pege ということになる。これが、バグなのか、gtbl 
プリプロセッサが自身の出力を窒息させる仕様なのか、それとも xman が 
gtbl プリプロセッサを２回も使わないようにされるべきなのかは、私にはわ
からない。いずれにしろ、テーブル（表）を使いたいのなら、自分でフォーマッ
トしておいて、.nf と .fi で挟み、フォーマットされないようにしよう。こ
の方法では、ボールド、イタリックが使えないが、表がなくなってしまうよう
なことはない。
<p>
Pic プリプロセッサを必要とする man page については、見たことがない。し
かし、私自身は、好ましくないと思う。上に例示したように、xman は pic プ
リプロセッサを使わないし、groff はやっぱり入力をめちゃくちゃにしてしま
うだろう。


<sect>配布すべきはソースかフォーマットされたドキュメンテーションか？

<p>
いくつかの選択枝の中から、長所（＋）と短所（−）を挙げてみよう。
<enum>
<item>ソースのみ：<p><verb>
  ＋ パッケージのサイズが小さい
  − groff のないシステムでは、利用できない
</verb>

<item>圧縮されていないフォーマット済ファイルのみ：<p><verb>
  ＋ groff がなくても利用できる
  − dvi ファイルや postscript ファイルを生成できない。
  − 圧縮された man page を取り扱うシステムにとっては、ディスク
     スペースの無駄
</verb>
<item>圧縮されたフォーマット済ファイルのみ：<p><verb>
  ＋ grof がなくても利用できる
  − dvi ファイルや postscript ファイルを生成できない。
  − 配布する圧縮フォーマットには何を使うかが問題。 .Z か、.z か、.gz 
     か、それともこれらのすべてか？
</verb>
<item>ソースと圧縮されていないフォーマット済ファイル：<p><verb>
  ＋ grof がなくても利用できる
  − 配布パッケージのサイズが大きくなる
  − いくつかのシステムでは、フォーマットされた man page は、圧
     縮されていることを前提としている。
  − groff のために準備される余分な情報
</verb>
</enum>

<p>
私の見解を言わせてもらえるのなら、ソースのみの配布が最上の方法である。
Groff のないシステムで利用で来ないという問題は重要でない。５００以上ある 
Linux ドキュメンテーションプロジェクトでの man page は、ソースのみの配
布である。XFree86 の man page はソースのみの配布である。FSF からの man
page もソースのみである。実際、私は、フォーマットされた man page がソ
フトウェアと一緒に配布されたのをみたことがない。システム管理者が、本当
に man page を利用可能にしようとしているのなら、groff もまた、インストー
ルされているだろう。

<sect>フォントに関する取り決めとは？
<p>
第一に、&bsol;fB や &bsol;fP のような直接のフォントオペレータを使わないこと。引
数を指定するマクロを用いる方が良い。この方法なら、よくある不都合、つま
り、範囲の終端で、フォントの変更を忘れて、次のフォントの変更の部分まで、
ボールドやイタリックが延長される不都合を避けることが出来る。嘘だと思う
だろうが、実際、良くあることなのだ。

<p>
Tmac.an マクロでは、以下のタイプフェイスが使える。<p>

<verb>
  .B      ボールド
  .BI     ボールドとイタリックが交互
  .BR     ボールドとローマンが交互
  .I      イタリック
  .IB     イタリックとボールドが交互
  .IR     イタリックとローマンが交互
  .RB     ローマンとボールドが交互
  .RI     ローマンとイタリックが交互
  .SM     小さめのサイズ （標準の９／１０のサイズ）
  .SB     小さくてボールド（小さめのサイズとボールドが交互になるのとは違う）
</verb>

<p>
「X と Y が交互」というのは、奇数番目の引数のタイプセットが、X となり、
偶数番目の引数のタイプセットが Y になることである。例えば、<p>

<verb>
 .BI "引数１はボールド " "引数２はイタリック " "ボールド " "そしてイタリック"
</verb>

ここで、引数に空白を含めるためには、ダブルクォーテーションマークが必要
である。
<p>
使えるものはこれくらいである。さて、次に、いろいろなタイプフェイスの使
い方を決めなければならない。（部分的に man(7) をそのまま引用してしまった）

<p>
UNIX の世界では、man page についての多くの気難しいしきたりがあるけれど
も、Linux 独自の 数百の man page が、我々の標準である。
<p>
関数については、引数は常に、形式のセクションにおいても、イタリックを使い、関
数の他の部分は、ボールドを使う。つまり、<p>
<verb>
	.BI "myfunction(int " argc ", char **" argv );	
</verb>

<p>
ファイル名は、形式セクションを除いて、常にイタリックで表す。形式セ
クションではインクルードされるファイルには、ボールドを使う。つまり、次
のようにする。<p>
<verb>
	.I /usr/include/stdio.h and
      	.B #include <stdio.h>
</verb>

<p>
特別のマクロ（普通大文字で表記される）には、ボールドを使う。<p>
<verb>
	.B MAXINT
</verb><p>
エラーコードを列挙する時には、コードをボールドにする。このリストは、普
通、.TP （ぶら下がりタグを伴った段落）マクロを次のように用いる。
<p><verb>
      .TP
      .B EBADF
      .I fd
      は、有効なファイル識別子ではない。
      .TP
      .B EINVAL
      .I fd
      は、読み出しに適していない。
</verb>

<p>
他の man page につての 言及（もしくは現在の man page のテーマについて
の言及）にはボールドを使う。マニュアルのセクション番号がある時には、空
白なしのローマンで表す。
<p><verb>
	.BR man (7)
</verb><p>
短縮形を使う時は、小さい文字を使った方が、見栄えが良いので、お勧めである。
<p><verb>
      .SM UNIX     .SM ASCII     .SM TAB      .SM NFS      .SM LALR(1)
</verb>


<sect>いかにして man page をより良くしていくか？
<p>
以下は、ドキュメンテーションの信頼性、可読性、見栄えを改善するためのガ
イドラインだ。
<p>

<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 &lt; %s &gt; %s
        zcat &lt; %s &gt; %s

  ＋ Makewhatis(8) は、名前セクションから、一行説明を抜き出すこ
     とができるか？
</verb>

<sect>＾H とか ＾_ などのない man page のテキストはどうすれば得られるか？
<p>
col(1) を見よう。col はバックスペースシーケンスを取り除ける。それも面
倒と言うのなら、次の様にタイプしよう。
<p>
<tscreen><verb>
funnyprompt% groff -t -e -mandoc -Tascii manpage.1 | col -bx \
&gt; manpage.txt
</verb></tscreen>
<p>
-t と -e のスイッチは、groff に tbl と eqn を使っての前処理を指定する。
前処理を必要としない man page にとっては、過剰な指定だけれども、数 CPU 
サイクルの無駄にしかならない。反対に、必要な時に -t のスイッチを指定し
ないと、表がめちゃくちゃにフォーマットされてしまい、有害である。Man
page に限らず、groff のドキュメントをフォーマットするために必要なコマ
ンドについては、次の様にタイプすれば、わかるだろう（grog コマンドを使
うから、"見当をつける" ことができるのほうがいいかな）。<p>
<p>
<tscreen><verb>
funnyprompt% grog /usr/man/man7/signal.7
groff -t -man /usr/man/man7/signal.7
</verb></tscreen>
<p>
"Grog" は、"GROff Guess" から来ており、その名の通り見当をつけることを
する。Grog が完全だったならば、その出力以上のオプションは必要ないんだけ
ど。私の経験では、grog は、マクロパッケージについては、間違うが、プリ
プロセッサについては正しかった。

<p>
以下は、私が書いた簡単な 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>
<p>
次のように、`man' コマンドの次の最初のフィルタとして使うこと。Groff に
よって出力される改行の数に、処理が依存しているから。
<p>
<tscreen><verb>
funnyprompt% man bash | strip-headers | col -bx > bash.txt
</verb></tscreen>


<sect>高品質のポストスクリプトの man page を得るには？
<p>
  
<tscreen><verb>
funnyprompt% groff -t -e -mandoc -Tps manpage.1 > manpage.ps
</verb></tscreen>
<p>
とやって、好みのポストスクリプトプリンタで印刷しよう。オプションの説明
については、10 節を見ること。


<sect>apropos と whatis を利用できるようにするには？  
<p>
使っているシステムにどんなコンパイラがインストールされており、どうすれ
ば起動できるかを知りたいとしよう。この質問（FAQだが）への答えは、次の
ようにすることである。
<p>
<tscreen><verb>
funnyprompt% apropos compiler
f77 (1) - Fortran 77 compiler
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler
</verb></tscreen>
<p>
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 に対しては、何も出力しない。

<p>
訂正及び提案を歓迎する。


<sect>著作権について
<p>
<verb>
 Copyright 1995,96 by Jens Schweikhardt 
 &lt;schweikh@noc.dfn.de&gt;
 Voice: ++49 7151 909516
</verb>
<p>
他に説明がない限り、Linux HOWTO ドキュメントは、それぞれの著作者に著作
権が属する。この著作権についての注意書が添付される限り、Linux HOWTO ド
キュメントは部分的又は全体で、物理的又は電子的に、複製及び配布をするこ
とが出来る。商業的な配布は、認められているし、推奨もされているが、著作
者には連絡をお願いしたい。
<p>
要約すれば、我々は、可能な限り多くの手段を介して、この情報の普及を推進
したい。しかし、この HOWTO ドキュメントの著作権は各著作者に残しておき
たいと考え、これらの HOWTO の再配布の計画については通知を受けたいので
ある。
<p>
もし、疑問があるなら、Linux HOWTO コーディネータである Greg Hankins に
連絡してほしい。電子メールアドレスは gregh@sunsite.unc.edu である。

&lsqb;訳者より&rsqb;
<p>
以下に著作権についての原文を念のため引用しておきます。

<p>
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.
<p>
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.
<p>
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.
<p>
If you have questions, please contact Greg Hankins, the Linux HOWTO
coordinator, at gregh@sunsite.unc.edu via email.

<p>
訳についてのコメント等は北山 &lt;kitayama＠dimgrey.av.sanyo.co.jp&gt; 
まで、お願いします。
<p>
最後になりましたがこの MANPAGE HOWTO の翻訳には、JF-ML での他の皆さ
んのいろいろなやりとりを参考にさせて頂きました。また、東芝の甲斐さんに
は、直接にアドバイスを頂きました。この場でお礼申し上げます。
</article>









