6.10 参考文献リストのマークアップ
ドキュメントの各節の多くには、モジュールドキュメントや外部ドキュメント
を指す参考文献のリストが入っています。こうしたリストは、\seealso
や\seealso* 環境を使って作成します。
これらの環境では、参考文献エントリを合理的なやり方で作成するための
追加のマクロを定義しています。
\seealso 環境は通常、節中で何らかの小節に入る直前の場所に配置
します。これは、ある節に関係した参考文献リンクが、
ドキュメントのハイパーテキスト解析を行う際に小節内に入り込んで
しまわないようにするためです。
HTML 出力の場合、このマクロの内容は本文の外側の ``サイドバー'' に
表示されます。\seealso* 環境は、参考文献リストを主コンテンツ
の一部として表示したい場合に使う点が異なります; \seealso* を
使うと、リストを特別扱いしてテキスト内から押し出したりしません。
- \begin{seealso}
\end{seealso}
-
この環境はヘッダ ``See also:'' を作成し、個々の参考文献を記述
するためのマークアップを定義します。
- \begin{seealso*}
\end{seealso*}
-
この環境は主コンテンツの一部として参考文献リストを生成する際に使います。
リストに特別にヘッダをつけることはなく、ドキュメントの本文から
押し出されることもありません。個々の参考文献を記述するために、
上と同じマークアップを提供しています。
以下のマクロの各々において、why は一つかそれ以上の完全な
文章で、大文字から始めねばなりません (文が識別子から始まる場合には
別で、大文字にする必要はありません)。また、適切な区切り文字で
終えねばなりません。
これらのマクロは \seealso や \seealso* 環境の中でしか
定義できません。
- \seelink
{url}{linktext}{why}
-
特定のオンラインリソースへの参照を示す場合、
ちゃんとした題名をそのリソースにつけられないが、短い説明を
リンクの後につけたい場合には \seelink マクロを使います。
タイトルで特定できるようなオンライン上のドキュメントには
\seetitle マクロを使い、オプションに URL を指定するように
してください。
- \seemodule
[key]{name}{why}
-
別のモジュールへの参照です。why は、なぜその参考文献が
興味の対象となるのかを示す短い説明にせねばなりません。
モジュール名は name で指定し、必要があれば key
でリンクキーを指定します。HTML および PDF 版では、
モジュール名部分は参照先のモジュールを指すハイパーリンクになります。
注意:
該当のモジュールは同じドキュメント内で記述されていなければ
なりません (対応する\declaremodule が必要です)。
- \seepep
{number}{title}{why}
-
Python Enhancement Proposal (PEP) への参照です。number は
PEP 編集者が割り当てた公式 PEP 番号でなければならず、
tiutle は PEP ドキュメントの公式版に書かれている人間可読な
タイトルでなければなりません。
このマクロは、ドキュメント中の注釈がつけられている節の内容が関係
しているインタフェースや言語機能 PEP への参照を読者に示すために
使います。
- \seerfc
{number}{title}{why}
-
IETF による Request for Comment (RFC) を参照します。
それ以外の点では、 \seepep とほとんど同じです。
このマクロは、ドキュメント中の注釈がつけられている節の内容が関係
しているプロトコルやデータ形式を仕様記述している RFC への参照を
読者に示すために使います。
- \seetext
{text}
-
任意のテキストtext を ``See also:'' リストに追加します。
このマクロはオフラインやオンラインの資料を \url マクロで
参照するために使えます。テキストは一つかそれ以上の完全な文で
構成しなければなりません。
- \seetitle
[url]{title}{why}
-
title という名前の外部ドキュメントに対する参照を追加します。
url を指定した場合、HTML 版では外部ドキュメントのタイトル部分が
ハイパーリンクになり、組版版のドキュメントでは表題の下に URL が
表示されます。
- \seeurl
{url}{why}
-
特定のオンラインリソースで、意味のあるタイトルがない場合には
\seeurl マクロを使って参照を行います。
はっきりしたタイトルのあるオンラインドキュメントの場合には、
\seetitle マクロを使い、そのオプションパラメタに URL を指定
して参照を行ってください。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。
