6. ドキュメント

GNU のプログラムには,理想的には,参照用と入門用両方を兼ね備えた 完全でフリーなドキュメントを付けなければならない. そのパッケージがプログラムしたり拡張したりすることが可能なら, 単なる使い方だけでなく,プログラミングや拡張方法についても 触れていなければならない.

6.1 マニュアルの正しい書き方
6.2 説明文とマニュアル
6.3 構成方法
6.4 マニュアルのライセンス
6.5 マニュアルのクレジット
6.6 印刷されたマニュアル
6.7 NEWS ファイル
6.8 変更履歴
6.9 マンページは重要ではない
6.10 他のマニュアルをどこまで参考にしてい良いか

                                参考にしてい良いか

6.1 マニュアルの正しい書き方

GNU システムの構成部分のドキュメントを書くのに望ましいフォーマットは, Texinfo フォーマット言語です.どの GNU パッケージも(理想的には) 参照用と学習用両方を目的とするドキュメントを Texinfo で書いたものを 持つべきです. Texinfo を使うことで, TeX を使って高品質のフォーマットされた本を 作ったり, Info ファイルを生成することが可能になります. Texinfo のソースから HTML 出力を生成することも可能です. Texinfo のマニュアルは,ハードコピー か info コマンド, あるいは GNU Emacs の Info （C-h i）で参照してください.

現在では,Docbook や Sgmltexi のような他のいくつかのフォーマットも 自動的に Texinfo に変換できます.Texinfo のドキュメントをこのような 変換で生成するのは,良い結果が得られるのであれば,かまいません.

プログラマは, ドキュメントの構成を, プログラムの実装の構成に 合わせるのが自然であると考えがちです. プログラムの構成については 良く知っているので. しかし, こういう構成はプログラムの使い方を 説明するのには向いていません. どちらかというと, ユーザにとっては 不親切で混乱させかねないのです.

段落の中の文章から, 話題を別々のマニュアルに分類することに至るまでの, 文書のあらゆる階層において, 正しい文書の構成方法というのは, 読者が読んでいるときに心に浮かんでいる考えや疑問に従うということです. こういう構成方法は, ソフトウェアの実装の構成と一致することもありますが, 異なることが多いと考えたほうが良いでしょう. 良い文書を書く方法を 学ぶうえで一つ重要なことは, 文書の構成をソフトウェアの実装に合わせている なら, 他にもっと良い方法があるはずだということに気が付くことです.

例えば, GNU システムの各プログラムの説明は, 一つのマニュアルに 納まるべきでしょう. しかし, このことは, それぞれのプログラムが それぞれのマニュアルを持つべきであるということは意味しません. それぞれのマニュアルを持つというのは, ユーザの理解を助ける構成 というよりは, プログラムの実装にしたがった構成です.

代わりに, それぞれのマニュアルは首尾一貫した話題をカバーすべきです. 例えば, diff と diff3 のマニュアルを別々に用意する代わりに, 我々は "comparison of files" いう名前のマニュアルを一つ用意し, 両方のプログラム, それに cmp の解説を含めています. これのプログラムを一緒に説明することで, 話題全体をはっきりさせることが 出来ます.

あるプログラムについて解説しているマニュアルには, そのプログラムの 全コマンド行引数と全内部コマンドが確かに書かれていなくてはなりませんし, その使用例を載せなくてはなりません. しかしマニュアルを機能の一覧として構成しないでください. 代わりに,論理的に副題で構成しましょう. そのプログラムが実際に行うことについて考えたときにユーザが疑問に思うであろう 事柄を説明しましょう.

一般に, GNU のマニュアルは入門書とリファレンスの両方の役割を 果たすべきです.Info を通じて各トピックを参照するのが簡単に出来なくては いけませんし,付録を除いて,頭から順番に読んでいっても良いようになって いなくてはなりません.また, GNU のマニュアルは初心者が読み始めるのに 適した入門遍がなくてはなりませんし,熟練者が必要とするあらゆる詳細についても 提供する必要があります. Bison のマニュアルが良い例になっています. Bison のマニュアルを眺めて 我々の意図を理解してください.

これは思ったほど難しいことではありません.各章を,そこで扱う話題を 論理的に分割し,それを節として順序良く並べ,それから中身の文章を 書きます.そうすることで,その章を頭から読み進めても理解できるように なります.本を章に分けるときや,節を段落から構成するときにも同じことが 言えます.標語的に言えば,文章のどの場所においても, 前の文章で提示されたもっとも基本的で重要な問題に注意を向けましょう.

必要なら,マニュアルの冒頭に章を追加して完全な入門遍とし,基本事項を カバーするようにしましょう.こうすることで,初心者がマニュアルの 残りの部分を理解するための指針となります. Bison のマニュアルが その良い例になっています.

リファレンスとするには,マニュアルには,関数,変数,オプション, それに,そのプログラムの一部である重要な概念を全て列挙した索引が なくてはなりません.全部を一つの索引にいれたものでも短いマニュアルには 充分かもしれませんが,複雑なパッケージの場合は複数の索引を 使った方が良いでしょう.Texinfo のマニュアルには良い索引項目の 作り方についての説明があります.section `Making Index Entries' in The GNU Texinfo Manual と section `Defining the Entries of an Index' in The GNU Texinfo manual を見て下さい.

GNU のドキュメントを書くのに, Unix のマンページの書き方は 手本にしないでください. Unix のマンページは大抵短すぎて, 構成がまずく, 背景にある考え方の説明が 適切ではありません. (もちろん, いくつか例外はありますが. ) また, Unix のマンページで使っているフォーマットは我々が GNU の マニュアルで使っているのと全然違っているという事情もあります.

マニュアル自体のバグの報告先の電子メールアドレスをそのマニュアルに 書いてください.

Unix のドキュメントで使われている "pathname" という言葉は使わないで ください.代わりに "file name" という二語を使ってください. 我々は "path" は,検索パス,つまりディレクトリ名のリストにしか使いません.

プログラムに対する入力が誤っていることを示すのに, "illegal" という 言葉は使わないでください. 入力の誤りには "invalid" を使うようにし, "illegal" は法律により罰せられる活動という意味に取っておきます.

6.2 説明文とマニュアル

プログラミングシステムの中には,Emacs のように,関数や,コマンド, 変数毎に説明文(documentation string)を提供しているものがあります. リファレンスマニュアルを 書く時に,この説明文を編集して,補足文をいくらか追加するという やりかたをしたくなるかも知れません.が,決してそうしてはなりません. そのやり方は根本的に間違っているのです.うまく書かれた説明文は マニュアル用には全く向いていないのです.

説明文は自立している必要があります.画面に表示された時, それを紹介したり説明したりする文はないのです. 一方,形式にはあまり拘らなくてかまいません.

マニュアルの中では,関数や変数を説明する文は孤立してはなりません. それは,セクションやサブセクションの文脈の中に現れるのです. セクションの冒頭には何らかの概念を説明する文を置き,それに,いくつかの 関数や変数に適用される一般的な観点を提供すべきでしょう. セクション内でそれ以前に現れる関数や変数の説明もまた話題についての 情報を提供するでしょう.独立したものとして書かれた説明は, そういう情報の一部を繰り返すことになります.これは冗長で良くありません. 一方,形式から外れるのは説明文では許されるても,マニュアルでは 受け入れられません.

良いマニュアルを書く上で,説明文の正しい使い道は, 良い文を書くための情報源として使う他にはありません.

6.3 構成方法

タイトルページには, マニュアルに記述されているプログラムやパッケージの バージョンを書かなくてはなりません. マニュアルの先頭ノードにも,この情報が必要です. プログラムとは独立に, あるいはプログラムより頻繁にマニュアルが変更されるな ら, マニュアルのバージョン番号も書いてください.

マニュアルに記述されているプログラム毎に, `program Invocation' あるいは `Invoking program'という名前のノードが必要です. ここで programは,説明されるプログラムの名前であり, 実行するためにシェルにタイプするものです. このノード（もしあればサブノードも）には,プログラムのコマンド行引数の 説明と起動方法（つまり,通常マンページに書かれるような情報）を明記します. `@example' で始め,そこには全オプションと引数のテンプレートを書きます.

あるいは,名前が上のパターンのどれか一つに一致するようなメニュー項目を どこかのメニューに入れます. こうすることで,ノードの実際の名前には関係なく, そのメニュー項目が指すノードをこの目的のためのノードとして識別します.

Info リーダプログラムの `--usage' の機能を使うと, ノードやメニュー項目を探して,関係するテキストを見つけるので, どの Texinfo ファイルにも入れるのが本質的に重要です.

１つのマニュアルで複数のプログラムを記述しているなら,そのマニュアルの 中にプログラム毎にそれを記述するノードを持つようにすべきです.

6.4 マニュアルのライセンス

GNU のマニュアルには,それが2,3ページよりも長いものなら,全て GNU Free Documentation License を使ってください. 短いドキュメントの集まりについても同じようにしてください. その場合,集まり全体に一つ GNU FDL のコピーがあれば充分です. 短いドキュメントが一つあるだけなら,非常に制限の緩い, コピーレフトでないライセンスを使って,長ったらしいライセンスで スペースを使うのを避けることができます.

GFDL を採用する方法についてのより詳しい説明は、 http://www.gnu.org/copyleft/fdl-howto.html を見て下さい。

ライセンスが GNU GPL でも GNU LGPL でもないマニュアルに、GPL や LGPL を含める義務はないことに注意して下さい。分厚いマニュアルの場合は、 プログラムのライセンスを含めるのは良い考えです。短いマニュアルの場合は、 プログラムのライセンスを入れると大きさが非常に大きくなってしまうようで あれば、多分取り込まない方が良いでしょう。

6.5 マニュアルのクレジット

主となるマニュアルの作者を著者として,タイトルページに明記して下さい. 企業がスポンサーとなっている作業の場合には,マニュアルの適切な場所に その企業に対する謝辞を入れるようにし,著者としては入れないでください.

6.6 印刷されたマニュアル

FSF は、GNU マニュアルのうちいくつかを印刷して発行している。 これらのマニュアルが売れるように、マニュアルのオンライン版では、 冒頭で、印刷されたマニュアルが入手可能であることを述べ、入手方法に ついての情報を、例えば http://www.gnu.org/order/order.html というページへのリンクをはって、指し示すこと。 ただし、この情報は、冗長であるので、印刷されたマニュアルには含める必要はない。

オンライン版のマニュアルで、ソースからマニュアルを印刷する方法を 説明するのも良いことである。

6.7 NEWS ファイル

マニュアルに加えて,各パッケージには `NEWS'という名前のファイルを 含めて,そこに記述に値するユーザに見える変更点を書きます. そして,新しいリリースの たびにファイルの先頭に項目を追加し,バージョンを明らかにしておきます. 古い項目を捨てずに,新しい項目の後ろに残しておきましょう. こうしておくと,以前のバージョンからアップグレードしたユーザは何が 最新かが分かります.

`NEWS'が長くなり過ぎたら,古い項目は `ONEWS'に移動させ, `NEWS' ファイルの最後に,`ONEWS'を参照するように 注意書きをつけましょう.

6.8 変更履歴

プログラムのソースファイルになされた変更については,全部,変更履歴に 書くようにしてください.目的は,将来バグについて調査をする人が, どの変更がバグを招いたのかを知ることができるようにするためです. 新しいバグは,変更したばかりのところで良く見つかります. もっと重要なことは,変更履歴があるとプログラムの別々の部分で 方針に食い違いが生じるのを防ぎます.それぞれの方針の食い違いが どのようにして生じたのか,それがどの部分で発生したのかが 履歴として残るからです.

6.8.1 変更履歴の考え方
6.8.2 変更履歴の形式
6.8.3 簡単な変更の場合
6.8.4 #ifdef の場合
6.8.5 部分的な変更を示すには

6.8.1 変更履歴の考え方

変更履歴は, 以前のバージョンが現在のバージョンとどれだけ違うかを説明する 変更取消しの一覧のようなものと考えることもできます. 現在のバージョンはすぐ見ることができます.それが何をしているのかの変更履歴は 必要ないのです. 変更履歴に求められるものは, 以前のバージョンがどのように 異なるかの明確な説明です.

変更履歴ファイルは普通 `ChangeLog' という名前で,それが置かれている ディレクトリ全体をカバーします.ディレクトリ毎にそのディレクトリ用の 変更履歴を置いても良いし,親ディレクトリの変更履歴に書いても構いません. どちらでも好きな方を選べます.

別の選択肢としては,変更履歴情報を RCS や CVS のような バージョン管理システムで記録することです.これは,rcs2log を使って 自動的に `ChangeLog'形式のファイルに変換することができます. Emacs では, C-x v a (vc-update-change-log) というコマンドで できます.

変更の目的を逐一書いたり, ある変更点と別の変更点との関係を書いたりする必要は ありません. 変更についての説明が必要だと思うこともあるでしょう. その場合,おそらくその通りでしょう.大いに説明を書いてください. ただし,その説明は,プログラム中にコメント文として書いてください. そうすれば,プログラムを読む人は必ずそのコメント文を見ることになるからです. 例えば,関数を一個追加したとき,変更履歴には "New function" と 書けば充分です.その関数が何をする関数かの説明はソースコード中で, その関数の定義の前にコメントとして書かれているはずだからです.

しかし, 変更量が多いときには, 変更目的の概要を示す一行が役にたつ こともあります.

`ChangeLog' に新しい項目を追加するのに一番簡単な方法は, Emacs の M-x add-change-log-entry コマンドを使うことです. 各項目には アスタリスクと変更したファイル名を書き,さらに変更した関数や変数名などを 丸括弧でくくって書いて, コロンをつけてください.その後に関数なり変数に 加えた変更を記述してください.

6.8.2 変更履歴の形式

以下に簡単な変更履歴の例をいくつか示します. まず,ヘッダ行で誰がいつ変更を行なったかを述べます. 次に,個々の変更の説明を書きます. (以下の例は,Emacs と GCC から取ったものです.)

1998-08-17 Richard Stallman <rms@gnu.org> * register.el (insert-register): Return nil. (jump-to-register): Likewise. * sort.el (sort-subr): Return nil. * tex-mode.el (tex-bibtex-file, tex-file, tex-region): Restart the tex shell if process is gone or stopped. (tex-shell-running): New function. * expr.c (store_one_arg): Round size up for move_block_to_reg. (expand_call): Round up when emitting USE insns. * stmt.c (assign_parms): Round size up for move_block_from_reg.

変更を行った関数名や変数名は略さずに全部書くことが重要です. 省略したり,複数の名前を組み合わせて書いたりしないでください. 保守を引き継いだ人が,関係する変更の履歴を関数名で検索する場合に, 名前が省略されていると,探しているものが見つからずに困ります.

例えば, `* register.el({insert,jump-to}-register)' のように 関数名をグループ化して略記する人がいますが,これはやめてください. これでは jump-to-register や insert-register で検索した場合に, 該当する変更履歴を見つけられないからです.

関連のない変更履歴の項目間は空行で区切ります.２つの項目が 同じ一つの変更の各部分を表していて関係があるなら, 空行を 入れないでください.その場合, 連続する項目が同じファイルにあるなら ファイル名とアスタリスクは省略できます.

関数名のリストが長い場合は,以下の例のように,行の途中で, `,' では なく `)' で閉じて分割し,継続行は `(' で始めるようにします.

* keyboard.c (menu_bar_items, tool_bar_items) (Fexecute_extended_command): Deal with `keymap' property.

6.8.3 簡単な変更の場合

変更がある程度簡単なものなら,変更履歴にあまり詳しく書く必要はありません.

ある関数の呼び出しシーケンスをより単純な形に変更して, それに合わせて 呼び出し側を全部その新しい呼び出しシーケンスに変更した, というような場合, 呼び出し側の変更全部についてを個々の項目を作る必要はありません. 呼び出される関数の項目に以下のように「呼び出し側のすべてを変更」 と書いておけば十分です.

* keyboard.c (Fcommand_execute): New arg SPECIAL. All callers changed.

コメントやドキュメントを変更した時は, 項目には関数の説明は書かずに, ファイル名だけで充分です. "Doc fix"とだけ書けば変更履歴としては 充分です.

ドキュメントファイルの変更履歴を作る必要はありません. ドキュメントの場合には, 修正困難なバグというのはあまり無いからです. ドキュメントは, 厳密な工学的な取扱いを必要とする部分には含まれません. 誤りを直すためにその履歴を知る必要はありません. ドキュメントに書かれていることと実際のプログラムの動作を比較すれば 良いのです.

6.8.4 #ifdef の場合

C 言語のプログラムでは,コンパイル時の条件節 #ifを良く 使います.変更が条件節に入っていることも多くあります. 完全に条件節の内側に入る新しい定義を追加することもあるでしょう. 変更履歴に,変更が適用される場合の条件を示すのは大変役に立ちます.

我々の約束では,条件節の変更を示すには,条件の名前(#define 名)を 鍵括弧で囲むことになっています.

以下の簡単な例は,条件節に関する変更を記述しています.ただし, 変更点に関数名や変数名が伴っていません.

* xterm.c [SOLARIS2]: Include string.h.

次の例は,完全に条件節に含まれる新しい #define を記述する項目です. マクロ FRAME_WINDOW_P のこの新しい #define は, HAVE_X_WINDOWS が #define された場合にのみ使われます.

* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.

次の例は, init_display という関数の中の変更を記述する項目です. 関数 init_display 全体としての定義は条件節の中には含まれていませんが, 変更点自体は, `#ifdef HAVE_LIBCURSES' という条件節に含まれます.

* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.

次の例は,あるマクロが定義されない場合にのみ有効になる 変更点に関する項目です.

(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.

6.8.5 部分的な変更を示すには

関数の変更のあった部分を, その部分が何をするものかを示すものを 角括弧で囲んで示すようにしましょう. 以下の例は, sh コマンドを扱う関数 sh-while-getopts の一部についての 変更を表すエントリです.

* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that user-specified option string is empty.

6.9 マンページは重要ではない

GNU プロジェクトにおいては,マンページは必須ではありません. GNU のプログラムは,マンページは必要ではありませんし,要求されることも ありません.中にはマンページを持っているものもありますが. 読者の自作のプログラムにマンページを含めるかどうかは読者自身が 決めれば良いことです.

どっちにするか決める際には,マンページを入れるということは, プログラムが変更される度にマンページも更新し続ける必要があるという ことを考えてください.マンページを保守するのに割く時間は, もっと役に立つ仕事に回せるはずです.

変更のほとんどない,簡単なプログラムの場合には,マンページの更新も たいした作業ではないでしょう.そういう場合には,既にマンページを 作成済なら,それを含めない理由はありません.

大量の変更が発生する大きなプログラムの場合には,マンページの更新作業は 大変な負荷になります.そのプログラムのユーザがマンページを書いてくれた とします.しかし,それを受け取るのは高くつくということがわかるでしょう. そのユーザがマンページの保守を全面的に引き受けてくれて,自分は何も する必要がないというのでない限り,断わったほうが良いでしょう. もし保守作業を引き受けてくれたとして,その人がある時点で保守作業を やめたとします.しかし,それを自分で引き継ごうとは思わなくて良いのです. 誰か他に保守してくれる人が現れるまで,配布物からマンページを抜いた方が 抜いてしまいましょう.

変更が少ないプログラムの場合,マンページを更新しなくても,相違点は 少ないからそのままでも役に立つと考える人もいるでしょう.その場合には, マンページの先頭に目立つように注意書きを書いて,マンページの更新は 行っていないこと,および,正しくは Texinfo のマニュアルを見るべきで あることを知らせましょう.注意書きには,Texinfo マニュアルの探し方も 書いておきます.

6.10 他のマニュアルをどこまで参考にしてい良いか

自分がドキュメントを書こうとしているプログラムについて,それを 解説しているフリーでない本やドキュメントファイルが存在することもあるでしょう.

そういうドキュメントを参考文献として使うことに問題はありません. ちょうど,新しい代数学の教科書の著者が,他の代数学の本を読むのが 問題ないのと同じようなものです. フィクションでない本はどんな本でも,ほとんどの部分が事実から 構成されています.この場合事実というのはあるプログラムがどのように 動作するのかという点に関する事実を指します.そして,そういう事実は 同じ主題について書く人誰にでも同じである必要があります. しかし,フリーでない文書からは,文書の構造や,言葉遣い,表や例などを コピーしないように注意する必要があります. フリーな文書からコピーするのはおそらく大丈夫でしょう. しかし,個々の場合については FSF に問い合わせてください.