6.11 索引生成のためのマークアップ
技術文書における索引の効果的な作成は、とりわけ作者がある事柄には詳しくても
索引の生成には不慣れな場合には非常に困難です。ドキュメントの困難さの
ほとんどは技術用語の範囲からきています: ある概念を説明する際に、
熟練者が使うような用語を入れるだけでは不十分です。ドキュメントの
作者は普通、自分の書いているドキュメントの領域においては熟練者であり、
初心者が立ち止まってしまうような用語を見つけ出すのはかなり難しいのです。
索引生成の本当に困難な側面は、ドキュメント作成ツールで補助できるような
領域のことがらではありません。とはいえ、ひとたび用語の内容を決めたら、
索引の作成を簡単にするのはツールの役割です。
様々な種類の索引を最小限の努力で生成できるようにするために
ドキュメント生成ソフトウェアが利用できるようなマークアップが提供
されています。加えて、6.3 節、 ``情報単位'' で説明した
多くの環境は、総合索引やモジュール索引上に適切なエントリを作成します。
以下のマクロは、索引情報を生成するために利用できます。これらはドキュメント
のプリアンブル内で使わねばなりません。
- \makemodindex
-
ドキュメントで多くのモジュールに対する参照が入った ``モジュール索引''
が必要な場合、プリアンブル内で使います。
このマクロは一連の\declaremodule マクロからデータファイル
libjobname.idx を生成します。このファイルは
makeindex プログラムで使われ、モジュール索引を入れたい場所に
\input を使って取り込めるようなファイルを生成します。
様々な概念について索引エントリを追加する上で便利なマクロがあります。
これらの多くはプログラミング言語や、Python に特有の概念です。
- \bifuncindex
{name}
-
name という名前の組み込み関数に対する索引エントリを追加します;
name の後ろに丸括弧を入れてはなりません。
- \exindex
{exception}
-
exception という名前の例外に対する索引エントリを追加します。
例外はクラスベースの例外でなければなりません。
- \kwindex
{keyword}
-
言語における予約語 (keyword、関数やメソッド呼び出しにおけるキーワード
引数とは違います) に対する索引エントリを追加します。
- \obindex
{object type}
-
組み込みオブジェクト型に対する索引エントリを追加します。
- \opindex
{operator}
-
"+" のような演算子に対する索引エントリを追加します。
- \refmodindex
[key]{module}
-
モジュール module に対する索引エントリを追加します;
module にアンダースコアが入っている場合、オプションのパラメタ
key には、module からアンダースコアを除去した名前を
指定せねばなりません。索引エントリ ``module (module)'' を生成
します。Python で書かれた非標準モジュールで使うためのものです。
- \refexmodindex
[key]{module}
-
\refmodindex のようなものですが、索引エントリは
``module (extension module)'' になります。
このマクロは Python 以外で書かれた非標準モジュールで使うためのものです。
- \refbimodindex
[key]{module}
-
\refmodindex のようなものですが、索引エントリは
``module (built-in module)'' になります。
このマクロは Python 以外で書かれた標準モジュールで使うためのものです。
- \refstmodindex
[key]{module}
-
\refmodindex のようなものですが、索引エントリは
``module (standard module)'' になります。
このマクロは Python で書かれた標準モジュールで使うためのものです。
- \stindex
{statement}
-
print やtry/finally のような、
構文型に対する索引エントリを追加します。
総合索引を簡単に作成する上で便利なマクロが提供されています。
索引エントリは、索引の様々な場所で語順を入れ替えて表示しなければ
なりません。これらのマクロは単に \index を使って複数の
索引エントリを作成するような単純なマクロです。こうしたマクロを
使って構築された索引エントリには、一次および二次の索引テキストが
入ります。
- \indexii
{word1}{word2}
-
二つの索引語からなる索引エントリを構築します。
\index{word1!word2} と
\index{word2!word1} を組み合わせて使うのと
同じです。
- \indexiii
{word1}{word2}{word3}
-
三つの索引語からなる索引エントリを構築します。
\index{word1!word2 word3}、
\index{word2!word3, word1}、および
\index{word3!word1 word2} を
組み合わせて使うのと同じです。
- \indexiv
{word1}{word2}{word3}{word4}
-
四つの索引語からなる索引エントリを構築します。
\index{word1!word2 word3 word4}、
\index{word2!word3 word4, word1}、
\index{word3!word4, word1 word2}、
および
\index{word4!word1 word2 word3} を
組み合わせて使うのと同じです。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。
