6.7 モジュール特有のマークアップ

この節で説明しているマークアップは、記述対象のモジュールに関する情報を提供するために使います。各モジュールのドキュメントは、それぞれ自身の \section の中に記述する必要があります。このマークアップは、節の先頭でよく使います。典型的な例は、以下のようになります:

\section{\module{spam} ---
         SPAM 機能へのアクセス}

\declaremodule{extension}{spam}
  \platform{Unix}
\modulesynopsis{\UNIX の SPAM 機能へのアクセス手段。}
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}

Python のパッケージ -- ひとまとまりの単位として記述できるようなモジュールの集合 -- は、モジュールと同じマークアップを使って解説します。パッケージ内のモジュール名は ``完全限定 (fully qualified)'' 形式で入力せねばなりません (つまり、パッケージ名を含めねばなりません)。例えば、 ``bar'' というパッケージ内の ``foo'' というモジュールは \module{bar.foo} と書き、リファレンスの先頭は以下のようになります:

\section{\module{bar.foo} ---
         \module{bar} パッケージ内のモジュール}

\declaremodule{extension}{bar.foo}
\modulesynopsis{\module{bar} パッケージ内の小さなモジュール}
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}

パッケージの名前もまた、\module でマークします。

\declaremodule [key]{type}{name}

二つのパラメタ: モジュールの種類 ("standard"、"builtin"、 "extension"、または"") と、モジュールの名前を必要とします。この節にリンクを張ったり参照を行ったりするための ``キー'' によっては、オプションのパラメタを指定せねばなりません。 ``キー'' は、モジュールの名前にアンダースコアが入っている場合にのみ用い、モジュール名からアンダースコアを取り除いた名前でなければなりません。 type パラメタは上に述べた値のいずれかでなければならず、そうでない値を指定するとエラーが出力されるので注意してください。パッケージに入っているようなモジュールの場合、name パラメタには完全限定形式の名前を指定せねばなりません。このマクロはモジュールを紹介する\section の先頭に置かねばなりません。

\platform {specifier}

モジュールの可搬性について述べるために使います。specifier はモジュールを利用できるようなプラットフォームを指定するキーをコンマで区切ったリストです。キーは短い識別子にします; 実際に使われている例には "IRIX"、"Mac"、"Windows"、"Unix" があります。あるプラットフォームを表す場合、すでに使われているキーがあるなら、それを使うようにするのが重要です。この情報は、モジュール索引や、 HTML形式、GNU info 形式の出力における注釈情報に使われます。

\modulesynopsis {text}

text はモジュールの短い ``一行の'' 説明で、各章の紹介の一部として使われることがあります。このマクロは \declaremodule の後ろに配置せねばなりません。モジュールの概要は、 \localmoduletable マクロによって挿入される一覧表の内容を構築する際に使われます。マークアップを行った場所では何のテキストも生成されません。

\moduleauthor {name}{email}

このマクロはモジュールの作者についての情報を符号化するために使われます。現在は出力生成に使われていませんが、モジュールの起源を判断する際に役立つはずです。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。