  THE LINUX MAN-PAGE-HOWTO
  Jens Schweikhardt<schweikh@noc.dfn.de>
  April 1996
  北山  公一 <kitayama@dimgrey.av.sanyo.co.jp>
  30 May 1996

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

  目次

  1. ドキュメンテーションについての若干の考察
  2. man page はいかにしてアクセスされるか？
  3. フォーマットされた man page はどのようにあるべきか？
  4. どうすれば、複数のプログラムや関数を一つの man page にまとめることができるか？
  5. どのマクロパッケージを使うべきか？
  6. どのプリプロセッサが使えるのか？
  7. 配布すべきはソースかフォーマットされたドキュメンテーションか？
  8. フォントに関する取り決めとは？
  9. いかにして man page をより良くしていくか？
  10. ＾H とか ＾_ などのない man page のテキストはどうすれば得られるか？
  11. 高品質のポストスクリプトの man page を得るには？
  12. apropos と whatis を利用できるようにするには？
  13. 著作権について

  ______________________________________________________________________

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

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

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

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

  1.  ドキュメンテーションについての若干の考察

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

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

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

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

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

  2.  man page はいかにしてアクセスされるか？

  作成する man page に正しい名称を与え、正しい場所にインストールするため
  には、man page がどのようにアクセスされるかについての正確な仕組みを知
  ることが必要である。man page はすべて、特定のセクションに所属してお
  り、このセクションは１文字で表されている。Linux での標準のセクションと
  その意味は次の通り。

  セクション  名前

      1       だれもが実行できるユーザコマンド
      2       システムコール、つまり、カーネルが提供する関数
      3       サブルーチン、つまり、ライブラリ関数
      4       デバイス、つまり、/dev ディレクトリのスペシャルファイル
      5       ファイルフォーマットの説明、例 /etc/passwd
      6       ゲーム（説明不要だろうネ）
      7       その他  例： マクロパッケージや取り決め的な文書
      8       システム管理者だけが実行できるシステム管理用のツール
      9       Linux 独自のカーネルルーチン用のドキュメンテーション
      n       新しいドキュメンテーション：よりふさわしい場所に移動されるだろう
      o       古いドキュメンテーション 猶予期間として保存されているもの
      l       独自のシステムについてのローカルなドキュメンテーション

  man page のためのソースファイル（フォーマットシステムへの入力）の名前
  は、対応するコマンド、関数もしくはファイルの名前で始まり、それにドット
  とセクション名が続く。例えば、passwd のファイルのフォーマットについて
  のドキュメンテーションを書く場合、ソースファイルの名称は、passwd.5 と
  しなければならない。この場合は、コマンドの名称とファイルの名称が同じ例
  である。また、passwd という名称のライブラリサブルーチンがあるかもしれ
  ない。セクションの設定は、これらの曖昧さを解決するために通常利用される
  方法である。すなわち、コマンドについての説明は、passwd.1 のファイル
  に、例としてあげたライブラリサブルーチンの説明は、passwd.3 のファイル
  に書かれることになる。

       時折、いくつかの文字が追加されて、例えば、 xterm.1x とか
       wish.1tk というファイル名となることがある。これの意味すると
       ころは、夫々が、Ｘウィンドウ又はＴｋのアプリケーションに対す
       るドキュメンテーションであることを明らかにすることである。マ
       ニュアルのブラウザによっては、この追加の情報を利用できる。例
       えば、xman は、利用可能なドキュメンテーションのリスト中
       に、xterm(x) や wish(tk) を使用する。
  n や o 及び l のセクションを使わないで欲しい。ファイルシステ
  ムスタンダードでは、これらのセクションは非難されている。数字
  のセクションを忠実に使って欲しい。

  既に存在するプログラム、関数又はファイルとの名前の衝突に注意すべきであ
  る。独自のエディタを作ってこれを 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 を正し
  い場所にインストールする一番安全な方法は、 /usr/man/man<s> のディレク
  トリに置くことである。しかし、よい Makefile は、例えば、make 変数
  MANDIR を用いて、ユーザーにベースディレクトリを選択できるようにしてい
  る。多くの GNU パッケージではディレクトリを指定できるプレフィクスオプ
  ションを利用して設定できる。 prefix=/what/ever としたとき、ベースディ
  レクトリとして /what/ever/man に、マニュアルがインストールされる。私が
  薦めるのは、同じ様な方法を用意することである。

       Linux ファイルシステム標準 (FS-Stnd) の出現により、事態はさ
       らに複雑になった。FS-Stnd 1.2 では、「/usr/man の構造におい
       て、異なる言語（複数の言語）で書かれた manual page をサポー
       トする約束を決める必要がある」とされている。これは、異なる言
       語の間で区別される別のディレクトリレベルを導入することで達成
       される。再び FS-Stnd 1.2 を引用すると：

       「usr/man の言語によるサブディレクトリの命名は、POSIX 1003.1
       標準の補遺 E （ロケール識別文字列について説明している）に基
       づく。すなわち、文化の異なる環境を記述するのに最も受け入れら
       れている方法である。「ロケール」文字列は：

         <言語>[_<地域>][.<文字セット>][,<バージョン>]

       （幾つかの共通のロケール文字列については、FS-Stnd を参照のこ
       と）

       このガイドラインによれば、man page のディレクトリは
       /usr/man/<locale>/man[1-9lno] となる。フォーマットされたド
       キュメントは、 /usr/man/<locale>/cat[1-9lno] におかれるべき
       だ。こうしないと、フォーマットされたドキュメントは、一種類の
       ロケールにだけしか準備できないことになる。

       しかし、私としては、現時点でこのようなディレクトリ構成に切換
       えることは薦めない。FS-Stnd 1.2 でも「全ての man page につい
       てコードセットと言語が統一されているなら、<locale> 文字列を
       省略して <mandir> にすべての manual page を保存してもよい」
       と許されている。例えば、英語だけの ASCII コードの manual
       page のシステムでは、/usr/man ディレクトリの man[1-9] のディ
       レクトリに manual page がおかれることになるだろう。（これ
       は、実際、伝統的な環境である）

       私は、全てのツール、例えば、xman, tkman, info その他の man
       page を利用するツールが、新しいディレクトリ構造に対応するま
       で、切換はしないつもりである。

  3.  フォーマットされた man page はどのようにあるべきか？

  まず、一つの例をあげて、その後、詳しく説明することにする。この文書の性
  質から、いくつものフォント（ボールドとかイタリック）を表示することはで
  きない。より詳しい説明は、「フォントに関する取り決め」を参照して欲し
  い。

  以下が、架空のプログラム foo についての man page である。

  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

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

     名称セクション
        名称のセクションは、必須のセクションである。名前のセクションがな
        ければ Man page は、北極点での冷蔵庫なみの価値しかない。名前セク
        ションは、カンマで区切られたプログラムや関数のリストとダッ
        シュ(-) に続く説明（通常は１行）、つまり、プログラムや関数、ファ
        イルが果たす機能の短い説明が含まれれた標準化された形式を持
        つ。makewhatis(8) は、名前セクションを利用して whatis データベー
        スファイルを作成する。makewhatis が利用するので、名前セクション
        が必須であり、形式が標準化されているのである。groff のソースで
        は、次のようにならないといけない。

             .SH 名称
             foo \-  bar ライブラリを調整する。

     ここで、\- は重要である。バックスラッシュはダッシュをコマンド名や一
     行説明にでてくるハイフォネーションのダッシュと区別するために必要で
     ある。

     形式セクション
        形式セクションは、指定できるオプションの簡単な説明が含まれる。関
        数の場合、その関数を含むインクルードファイルとプロトタイプ宣言が
        記載され、プログラマは、引数の型や数、関数の返り値の型を知ること
        が出来る。

      説明セクション
        説明セクションでは、この０と１のデータの並びつまりプログラムに一
        体全体どんな価値があるかについて、詳しい説明が記載される。あなた
        が書く場合、あなたの持てる知識全部を書くようにする。いわば、名声
        の殿堂なのだ。他のプログラマやユーザの称賛を得るためには、詳しく
        て信頼のおける記載にしなければならない。どの引数が何のためにあ
        り、どのようなファイルフォーマットが用いられ、どのようなアルゴリ
        ズムが、プログラムの処理に用いられているかを説明しなければならな
        い。

     オプションセクション
        オプションのセクションでは、オプションがプログラムの動作に与える
        影響について説明される。自分のプログラムだから、オプションについ
        てはよく知ってるよね？

     ファイルセクション
        ファイルのセクションでは、プログラムまたは関数が使用するファイル
        を列挙する。例えば、設定ファイル、初期ファイル、プログラムが直接
        操作するファイルなどのこと。これらのファイルのフルパス名を記載
        し、ユーザの好みに合わせてインストールするディレクトリを変更でき
        るインストール処理を作ることはいい考えである。例えば、groff のマ
        ニュアルでは、デフォルトのプレフィクスは /usr/local であり、通
        常、 /usr/local/lib/groff/* のファイルを参照する。しかし、'make
        prefix=/opt/gnu' と実行してインストールすると、man page での参照
        は、 /opt/gnu/lib/groff/＊ のファイルに対するように変更される。

     環境変数セクション
        環境変数のセクションでは、プログラムや関数に関する環境変数全てが
        列挙され、もちろん、どう影響するかの説明がある。普通、環境変数に
        より、パス名やファイル名、デフォルトのオプションが指定される。

     診断メッセージセクション
        診断メッセージセクションには、プログラムからのよくあるエラーメッ
        セージの簡単な説明とエラーメッセージに基づきどうすべきかについて
        記載すべきだ。プログラムを実行した時に表示されるかも知れない、シ
        ステムエラーメッセージ（perror(3) からのもの）とか、致命的なシグ
        ナル（psignal(3) からのもの）については、説明する必要はない。

     バグセクション
        バグセクションは、理想を言えば、ないほうが良い。勇気があるなら、
        プログラムの制限とか、わかっているプログラムの不便なところ、他の
        人がおかしいとみなす機能について、書けば良い。勇気がなけれ
        ば、"将来の予定" （TO DO）とでも名前を変えよう ;-)

     著者のセクション
        プログラムの動作とかドキュメントにエラーがいっぱいあって、バグレ
        ポートを送って欲しいのなら、著者のセクションを設けることは良い考
        えだが...

     関連項目セクション
        関連項目のセクションは、関連する man page のアルファベット順のリ
        ストであり、慣習的に、最後におかれる。

  上に説明したセクションに合わない内容については、別のセクションをつくり
  出しても構わない。

  では、正確には、どのようにして man page のソースを書けば良いのだろう
  か？  そう来ると、思っていたよ、ルーク。ソースファイルは次のようにな
  る。

   .\" このソースファイルを次のように処理すること。
   .\" 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)

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

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

  1. それぞれの名称に対してファイルのコピーを用意する。

  2. ハードリンクで全ての man page をリンクする。

  3. 実際の man page をシンボリックリンクで指定する。

  4. groff の .so マクロによるソース機能を利用する。

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

  つまり、次のようにする。

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

           .so man1/foo.1

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

  5.  どのマクロパッケージを使うべきか？

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

       もし、tmac.doc マクロを使いたいと言うことなら、以下のポイン
       タを参照してほしい。

             http://www.bsdi.com/bsdi-man

       そこには、検索可能なインデックスがある。'mdoc' と入力すれ
       ば、mdoc(7)、 mdoc.samples(7) 及びBSD man page を書くための
       チュートリアルが得られる。

  6.  どのプリプロセッサが使えるのか？

  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 をフォーマットする
  のに、次のコマンドを用いる。

       gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man \
       > /tmp/xmana01760 2> /dev/null

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

  Pic プリプロセッサを必要とする man page については、見たことがない。し
  かし、私自身は、好ましくないと思う。上に例示したように、xman は pic プ
  リプロセッサを使わないし、groff はやっぱり入力をめちゃくちゃにしてしま
  うだろう。

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

  いくつかの選択枝の中から、長所（＋）と短所（−）を挙げてみよう。

  1. ソースのみ：

       ＋ パッケージのサイズが小さい
       − groff のないシステムでは、利用できない

  2. 圧縮されていないフォーマット済ファイルのみ：

       ＋ groff がなくても利用できる
       − dvi ファイルや postscript ファイルを生成できない。
       − 圧縮された man page を取り扱うシステムにとっては、ディスク
          スペースの無駄

  3. 圧縮されたフォーマット済ファイルのみ：

       ＋ grof がなくても利用できる
       − dvi ファイルや postscript ファイルを生成できない。
       − 配布する圧縮フォーマットには何を使うかが問題。 .Z か、.z か、.gz
          か、それともこれらのすべてか？

  4. ソースと圧縮されていないフォーマット済ファイル：

       ＋ grof がなくても利用できる
       − 配布パッケージのサイズが大きくなる
       − いくつかのシステムでは、フォーマットされた man page は、圧
          縮されていることを前提としている。
       − groff のために準備される余分な情報

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

  8.  フォントに関する取り決めとは？

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

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

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

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

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

  ここで、引数に空白を含めるためには、ダブルクォーテーションマークが必要
  である。

  使えるものはこれくらいである。さて、次に、いろいろなタイプフェイスの使
  い方を決めなければならない。（部分的に man(7) をそのまま引用してしまっ
  た）

  UNIX の世界では、man page についての多くの気難しいしきたりがあるけれど
  も、Linux 独自の 数百の man page が、我々の標準である。

  関数については、引数は常に、形式のセクションにおいても、イタリックを使
  い、関数の他の部分は、ボールドを使う。つまり、

          .BI "myfunction(int " argc ", char **" argv );

  ファイル名は、形式セクションを除いて、常にイタリックで表す。形式セク
  ションではインクルードされるファイルには、ボールドを使う。つまり、次の
  ようにする。

          .I /usr/include/stdio.h and
          .B #include <stdio.h>

  特別のマクロ（普通大文字で表記される）には、ボールドを使う。

          .B MAXINT

  エラーコードを列挙する時には、コードをボールドにする。このリストは、普
  通、.TP （ぶら下がりタグを伴った段落）マクロを次のように用いる。

        .TP
        .B EBADF
        .I fd
        は、有効なファイル識別子ではない。
        .TP
        .B EINVAL
        .I fd
        は、読み出しに適していない。

  他の man page につての 言及（もしくは現在の man page のテーマについて
  の言及）にはボールドを使う。マニュアルのセクション番号がある時には、空
  白なしのローマンで表す。

          .BR man (7)

  短縮形を使う時は、小さい文字を使った方が、見栄えが良いので、お勧めであ
  る。

        .SM UNIX     .SM ASCII     .SM TAB      .SM NFS      .SM LALR(1)

  9.  いかにして man page をより良くしていくか？

  以下は、ドキュメンテーションの信頼性、可読性、見栄えを改善するためのガ
  イドラインだ。
    ＋ コマンドが動作するかやってみる。この時も 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) は、名前セクションから、一行説明を抜き出すこ
       とができるか？

  10.  ＾H とか ＾_ などのない man page のテキストはどうすれば得られる
  か？

  col(1) を見よう。col はバックスペースシーケンスを取り除ける。それも面
  倒と言うのなら、次の様にタイプしよう。

       funnyprompt% groff -t -e -mandoc -Tascii manpage.1 | col -bx \
       > manpage.txt

  -t と -e のスイッチは、groff に tbl と eqn を使っての前処理を指定す
  る。前処理を必要としない man page にとっては、過剰な指定だけれども、数
  CPU サイクルの無駄にしかならない。反対に、必要な時に -t のスイッチを指
  定しないと、表がめちゃくちゃにフォーマットされてしまい、有害であ
  る。Man page に限らず、groff のドキュメントをフォーマットするために必
  要なコマンドについては、次の様にタイプすれば、わかるだろう（grog コマ
  ンドを使うから、"見当をつける" ことができるのほうがいいかな）。

       funnyprompt% grog /usr/man/man7/signal.7
       groff -t -man /usr/man/man7/signal.7

  "Grog" は、"GROff Guess" から来ており、その名の通り見当をつけることを
  する。Grog が完全だったならば、その出力以上のオプションは必要ないんだ
  けど。私の経験では、grog は、マクロパッケージについては、間違うが、プ
  リプロセッサについては正しかった。

  以下は、私が書いた簡単な perl のスクリプトで、ページヘッダとフッタを削
  除できる。これを使えば、長くて詳細な man page を印刷する時に、数ページ
  は、得することができる。"strip-header" という名でファイルに保存して
  "chmod 755" として欲しい。

          #!/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;

  次のように、`man' コマンドの次の最初のフィルタとして使うこと。Groff に
  よって出力される改行の数に、処理が依存しているから。

       funnyprompt% man bash | strip-headers | col -bx > bash.txt

  11.  高品質のポストスクリプトの man page を得るには？

       funnyprompt% groff -t -e -mandoc -Tps manpage.1 > manpage.ps

  とやって、好みのポストスクリプトプリンタで印刷しよう。オプションの説明
  については、10 節を見ること。

  12.  apropos と whatis を利用できるようにするには？

  使っているシステムにどんなコンパイラがインストールされており、どうすれ
  ば起動できるかを知りたいとしよう。この質問（FAQだが）への答えは、次の
  ようにすることである。

       funnyprompt% apropos compiler
       f77 (1) - Fortran 77 compiler
       gcc (1) - GNU C and C++ compiler
       pc (1) - Pascal compiler

  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 に対しては、何も出力しない。

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

  13.  著作権について

   Copyright 1995,96 by Jens Schweikhardt
   <schweikh@noc.dfn.de>
   Voice: ++49 7151 909516

  他に説明がない限り、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 での他の皆さん
  のいろいろなやりとりを参考にさせて頂きました。また、東芝の甲斐さんに
  は、直接にアドバイスを頂きました。この場でお礼申し上げます。

