次のページ 前のページ 目次へ

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) は、名前セクションから、一行説明を抜き出すこ
     とができるか?


次のページ 前のページ 目次へ