[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

8. 相互参照

相互参照(Cross references)は,同じまたは異なるTexinfoファイルの他 の部分へ読者を導くために使用します.Texinfoでは,ノードとアンカーが相互 参照が参照する場所です.

What References Are For  What cross references are for.
8.1 様々な相互参照コマンド  A summary of the different commands.
8.2 相互参照の部品  A cross reference has several parts.
8.3 `Top'ノードに名前を付ける  How to refer to the beginning of another file.
8.4 @ref  A reference for the last part of a sentence.
8.5 @pxref  How to write a parenthetical cross reference.
8.6 @inforef  How to refer to an Info-only file.
8.7 @uref{url[, text][, replacement]}  How to refer to a uniform resource locator.

What References Are For

参照されるもの

いつもではありませんが,ほとんどの印刷されたドキュメントは順番に読むよう に設計されています.人々は,必要なとき提出されるべき情報を見つけるために, 前後にページをめくるのが嫌になります.

しかしドキュメントには,現在の文脈に対しては詳しすぎたり主要でなかったり する情報もあります.そのような情報へのアクセスを提供するため相互参照を使 用してください.また,オンラインヘルプシステムやリファレンスマニュアルは. 小説とは異なります.そのようなドキュメントを最初から最後まで順番に読む人 はほとんどいません.代わりに,人々は必要なところを拾い読みします.このた め,そのようなものでは,読者が読まなかった可能性のある他の情報を見つける とき役に立つ相互参照を多く含めるべきです.

印刷されたマニュアルでは,完全に他のマニュアルでない限り,相互参照は結果 としてページ参照となり,他のマニュアルの場合は相互参照はマニュアルの名前 になります.

Infoでは,相互参照は結果としてInfoの`f'コマンドに続いて使用可能な項 目となります.(See Info file `info', node `Help-Adv'.)

様々な相互参照コマンドは,ノード(やアンカー see section @anchor)を相互参照の位置を定義するために使用しま す.これはInfoの環境の話で,そこでの相互参照は指定した場所に移動します. TeXもノードを相互参照の位置を定義するために使用しますが,動作は明白で はありません.TeXがDVIファイルを生成するとき,それは,それぞれのノー ドのページを記録し参照を作成する際にページ番号を使用します.このため,印 刷されるだけのマニュアルを書くだけでオンラインで使用しない場合でさえ,相 互参照する場所に名前をつけるために@node行を書く必要があります.


8.1 様々な相互参照コマンド

四つの様々な相互参照のコマンドがあります.

@xref
印刷されたマニュアルでの`See ...'や,Infoでの相互参照の `*Note name: node.'を告げる文を開始するために使用されま す.

@ref
文中や主に文の最後で使用します.Infoでは@xrefと同じです.印刷さ れたマニュアルでは参照だけを生成し,前に`See'を生成しません.

@pxref
Infoファイルや印刷された本に適した参照を生成するためカッコ内で使用します. 印刷されたマニュアルでは小文字の`see'で始まります.(`p'は `parenthesis'です.)

@inforef
Infoファイルでの参照を作成するために使用し,印刷されたマニュアルにはあり ません.

(@citeコマンドは,Infoと関係の無い本やマニュアルへの参照を作成す るために使用され,それゆえ,指し示すノードはありません.See section @cite.)


8.2 相互参照の部品

相互参照のコマンドは一つの引数のみを要求し,それは参照するノード名です. しかし,相互参照コマンドは四つの追加の引数を含むことができます.これらの 引数を使用することで,Infoに対する相互参照名,トピックの記述や印刷物での セクションのタイトル,異なるInfoファイルの名前,そして異なる印刷されたマ ニュアルの名前を提供することが可能になります.

簡単な相互参照の例は以下のようになります.

 
@xref{Node name}.

これは,以下を生成します.

 
*Note Node name::.

そして,以下を生成します.

See Section nnn [Node name], page ppp.

完全な五つの部分を持つ相互参照は以下のようになります.

 
@xref{Node name, Cross Reference Name, Particular Topic,
info-file-name, A Printed Manual}, for details.

これは,以下を生成します.

 
*Note Cross Reference Name: (info-file-name)Node name,
for details.

Infoではこうなります.

See section "Particular Topic" in A Printed Manual, for details.

印刷された本ではこうなります.

相互参照に対する五つの利用可能な引数は,以下の通りです.

  1. ノードやアンカー名です(必須).これは,相互参照がたどっていく場所です.印 刷されたドキュメントでは,ノードの場所は同じドキュメント内を参照するため だけのページ参照を提供します.

  2. 相互参照名がノード名と異なっている場合のInfo参照に対する相互参照名です. この引数を含める場合,それは相互参照の最初の部分になります.通常省略され ます.

  3. トピックの記述やセクション名です.これはよくセクションのタイトルになりま す.これは印刷されたマニュアルでの参照名として使用されます.省略された場 合,ノード名が使用されます.

  4. 参照先が現在のファイルと異なる場合,参照先があるInfoファイル名です.Info リーダは自動的に追加するので,ファイル名の`.info'接尾子は不要です.

  5. 異なるTexinfoファイルで印刷されたマニュアル名です.

完全な五つの引数を持つ相互参照のテンプレートは,以下のようになります.

 
@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

一つ,二つ,三つ,四つ,そして五つの引数を持つ相互参照は,@xref の記述に続けて,別々に記述されます.

相互参照では,@node行と正確に同じ方法で,同じように大文字小文字 を使用して,ノード名を書いてください.そうしない場合,フォーマッタは参照 を見つけることができません.

段落で相互参照を書くこともできますが,InfoとTeXが,それぞれの様々なコ マンドの出力をどのようにして書式化するのかに注意してください.それは, @xrefを文の最初に書く.@pxrefをカッコ内でのみ書くなどで す.

@xrefコマンドは文の最初での相互参照を生成します.Info書式化コマ ンドはそれをInfo相互参照に変換し,Infoの`f'で他のノードへ直接行くこ とが可能です.TeX植字コマンドは,それをページ参照や他の本やマニュアル への参照に変換します.

参照のように見えるものと必要条件  What a reference looks like and requires.
8.2.1 一つの引数を用いた@xref  @xref with one argument.
8.2.2 二つの引数を用いた@xref  @xref with two arguments.
8.2.3 三つの引数を用いた  @xref with three arguments.
8.2.4 四つと五つの引数を用いた@xref  @xref with four and five arguments.

参照のように見えるものと必要条件

よくあるInfo相互参照は,以下のようになります.

 
*Note node-name::.

または,以下のようになります.

 
*Note cross-reference-name: node-name.

TeXでは,相互参照は以下のようになります.

See Section section-number [node-name], page page.

または,以下のようになります.

See Section section-number [title-or-topic], page page.

@xrefコマンドは,Infoファイルや印刷物でピリオドやカンマを相互参 照の終りに生成しません.ピリオドやカンマは自分で書く必要があります. (8)そうしない場合,参照の 終りを認識しません.(@pxrefコマンドは異なる動作をします. See section @pxref.)

注意してください:ピリオドやカンマを,@xrefに続ける 必要があります.相互参照の終了で要求されます.このピリオドやカ ンマは,Infoファイルと印刷されたマニュアルの両方の出力に現れます.

@xrefはInfoをノード名で参照する必要があります.@nodeをノー ドの定義に使用してください(see section 6.3.2 @node行の書き方).

@xrefはカッコ内に,カンマで分けられたいくつかの引数が続きます. これらのカンマの前後の空白は無視されます.

相互参照はノード名のみ必要です.しかし,それは最大四つまで追加引数を含む ことができます.これらの変数はそれぞれ,幾分異なるように見える相互参照を 生成します.

注意してください:カンマは相互参照で引数を分離します.フォーマッ タがそれらをセパレータと間違えないように,タイトルや他の部分にそれらを含 めるのを避けてください.


8.2.1 一つの引数を用いた@xref

@xrefの最も簡単な形式は,同じInfoファイルの他のノード名を一つの引 数として持つものです.Infoフォーマッタは,Infoリーダが参照へジャンプでき る出力を生成します.TeXはページとセクション番号を指定する出力を生成し ます.

例えば,以下のようにします.

 
@xref{Tropical Storms}.

これは,以下を生成します.

 
*Note Tropical Storms::.

そして,以下を生成します.

See Section 3.1 [Tropical Storms], page 24.

(前の例では,閉じカッコにピリオドが続くことに注意してください.)

相互参照の後に,以下のように文節を書くことが可能です.

 
@xref{Tropical Storms}, for more info.

それは,以下を生成します.

 
*Note Tropical Storms::, for more info.

そして,以下を生成します.

See Section 3.1 [Tropical Storms], page 24, for more info.

(前の例では,閉じカッコはカンマと文節が続き,それにはピリオドが続くこと に注意してください.)


8.2.2 二つの引数を用いた@xref

二つの引数を用いた場合,二番目はInfo相互参照の名前として使用され,一方,最 初のものは相互参照が示すノード名のままです.

テンプレートは以下のようになります.

 
@xref{node-name, cross-reference-name}.

例えば,以下のようにします.

 
@xref{Electrical Effects, Lightning}.

以下を生成します.

 
*Note Lightning: Electrical Effects.

そして,以下を生成します.

See Section 5.2 [Electrical Effects], page 57.

(前の例では,閉じカッコはピリオドが続き,ノード名が印刷され,相互参照は印 刷されないことに注意してください.)

相互参照の後に,以下のように文節を続けることができます.

 
@xref{Electrical Effects, Lightning}, for more info.

以下を生成します.

 
*Note Lightning: Electrical Effects, for more info.

そして,以下を生成します.

See Section 5.2 [Electrical Effects], page 57, for more info.

(前の例では,閉じカッコはカンマと文節が続き,それにはピリオドが続くことに 注意してください.)


8.2.3 三つの引数を用いた

三番目の引数は,TeX出力のノード名を置換します.三番目の引数は,印刷物 でのセクション名にするか,セクションで述べられているトピックを述べるべき です.参照を印刷したとき読みやすいように,頭文字を大文字にしたいことも多 いでしょう.構文や意味としてノード名が適切でないときは,三番目の引数を使 用してください.

相互参照のタイトルやトピックや,その他のあらゆるセクションで,カンマの配 置を避けることを覚えておいてください.フォーマッタは,カンマに従い引数の 相互参照を分けます.タイトルやセクションのカンマは,それを二つの引数に分 けます.参照では,タイトルをカンマ無しで"Clouds, Mist, and Fog"のよう に書く必要があります.

また,相互参照を終了するために,カンマやピリオドを@xrefの閉じカッ コの後に書くことを覚えておいてください.以下の例では,文節が終端のカンマ に付きます.

テンプレートは以下のようになります.

 
@xref{node-name, cross-reference-name, title-or-topic}.

例えば,以下のようにします.

 
@xref{Electrical Effects, Lightning, Thunder and Lightning},
for details.

以下を生成します.

 
*Note Lightning: Electrical Effects, for details.

そして,以下を生成します.

See Section 5.2 [Thunder and Lightning], page 57, for details.

三番目の引数が与えられていて,二番目が空の場合,三番目の引数が両方に与え られます.(二つのカンマが並んで,二番目の引数が空だということを示してい る方法に注意してください.)

 
@xref{Electrical Effects, , Thunder and Lightning},
for details.

以下を生成します.

 
*Note Thunder and Lightning: Electrical Effects, for details.

そして,以下を生成します.

See Section 5.2 [Thunder and Lightning], page 57, for details.

実際問題として,ノード名とセクションタイトルが同じ場合は,相互参照を最初 の引数で書き,ノード名とタイトルが異なる場合は,一番目と三番目の引数で書 くことが最善です.

The GNU Awk User's Guideでいくつかの例は以下のようになっています.

 
@xref{Sample Program}.
@xref{Glossary}.
@xref{Case-sensitivity, ,Case-sensitivity in Matching}.
@xref{Close Output, , Closing Output Files and Pipes},
  for more information.
@xref{Regexp, , Regular Expressions as Patterns}.


8.2.4 四つと五つの引数を用いた@xref

相互参照では,四番目の引数はリファレンスが現れるファイルと異なるInfoファ イルのアンカー名を指定し,五番目の引数は印刷されたマニュアルでのそのタイ トルを指定します.

カンマやピリオドを,相互参照を終了する@xrefの閉じカッコに続ける 必要があることを覚えておいてください.以下の例では,終端のカンマに文節が 続きます.

テンプレートは以下のようになります.

 
@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

以下が例です.

 
@xref{Electrical Effects, Lightning, Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

以下を生成します.

 
*Note Lightning: (weather)Electrical Effects, for details.

Infoファイルの名前はカッコで囲まれ,前にノード名があります.

印刷されたマニュアルでは,参照は以下のようになります.

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

印刷されたマニュアルのタイトルは,イタリック体で植字されます.他のマニュ アルを参照するときは,相互参照が参照するページをTeXは知ることができな いので,ページ番号はありません.

長いバージョンの@xrefを使用するとき,二番目に引数を省略することも よくあります.この場合,トピックを記述する三番目に引数はInfoでの相互参照 名として使用されます.

テンプレートは以下のようになります.

 
@xref{node-name, , title-or-topic, info-file-name,
printed-manual-title}, for details.

それは,以下を生成します.

 
*Note title-or-topic: (info-file-name)node-name, for details.

そして,以下を生成します.

See section title-or-topic in printed-manual-title, for details.

例えば,以下のようにします.

 
@xref{Electrical Effects, , Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

以下を生成します.

 
*Note Thunder and Lightning: (weather)Electrical Effects,
for details.

そして,以下を生成します.

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

滅多にありませんが,単一の印刷されたマニュアルにある他のInfoファイルへ参 照したいときもあります -- それは,複数のTexinfoファイルが同じTeXの実 行に組み込まれるにもかかわらず,別々のInfoファイルを作成するときです.こ の場合,四番目の引数のみを指定し,五番目はその必要がありません.


8.3 `Top'ノードに名前を付ける

相互参照では,常にノードを名付ける必要があります.これは,マニュアル全体 を参照するために,@xrefコマンドの最初の引数として書き込むことで `Top'ノードを識別する必要があるということを意味します.(これは,メニュー 項目を書く方法と異なります.Referring to Other Info Filesを参照してください.)同時に,印刷された相互参照で有意義なセク ショントピックやタイトルを(単語`Top'の代わりに)提供するために, @xrefコマンドの三番目の引数として適切な項目を書く必要があります.

このため,The GNU Make Manualへの相互参照を作成するために,以下の ように書いてください.

 
@xref{Top, , Overview, make, The GNU Make Manual}.

それは,以下を生成します.

 
*Note Overview: (make)Top.

そして,以下を生成します.

See section "Overview" in The GNU Make Manual.

この例では,`Top'が最初のノード名で,`Overview'がマニュアルの 最初のセクション名です.


8.4 @ref

@refは印刷物で`See'を生成せず,参照のみを生成する以外, @xrefとほとんど同じです.これは,文の終りの部分にするとき役に立 ちます.

例えば,以下のようにします.

 
For more information, see @ref{Hurricanes}.

以下を生成します.

 
For more information, see *Note Hurricanes::.

そして,以下を生成します.

For more information, see Section 8.2 [Hurricanes], page 123.

@refコマンドは,著者が表現する方法として,印刷されたマニュアルに 適しているが,Info書式では悪く見えるものを導き出すときもあります.使用者 が印刷物とInfo書式の両方で使用することを心に留めておいてください.

例えば,以下のようにします.

 
Sea surges are described in @ref{Hurricanes}.

以下を生成します.

Sea surges are described in Section 6.7 [Hurricanes], page 72.

以上は印刷されたマニュアルで,Infoでは以下のようになります.

 
Sea surges are described in *Note Hurricanes::.

注意:ピリオド,カンマ,または正しいカッコを,@refコマン ドの後に二つ以上の引数とともに書く必要があります.そうしない場合, Infoは相互参照の項目を見つけることができず,相互参照を追う試みは失敗しま す.一般的な規則として,ピリオドやカンマを,全ての@refコマンドの 後に書くべきです(9).これは,印刷されたマニュアルでもInfo出力 でも最善に見えます.


8.5 @pxref

丸カッコの参照コマンド@pxrefは,@xrefとほとんど同じです が,丸カッコの中でのみ使用し,コマンドの閉じカッコの後にカンマや ピリオドを入力しません.コマンドは二つの点で@xrefと異なり ます.

  1. TeXは印刷されたマニュアルに対し,大文字の`See'ではなく小文字の`see'を 用いて参照を植字します.

  2. Info書式化コマンドでは,自動的に閉じコロンやピリオドで参照を終りにします.

書式化の一つの形式は自動的に閉じる句読点を挿入し,もう一つはそうしないの で,@pxrefは他の文の一部として丸カッコ内でのみ使用すべき です.また,@xrefで行うような,参照後に句読点を挿入すべきではあ りません.

@pxrefは,印刷物とInfoファイルの両方で出力が正しく見え,丸カッコ が正しく動作するように設計されています.印刷されたマニュアルでは,閉じる カンマやピリオドは丸カッコ内の相互参照の後に続きません.そのような句読点 は間違いです.しかしInfoファイルでは,適切な閉じる句読点をInfoが終りとし て認識できるように,相互参照に続ける必要があります.@pxrefで,出 力の一つの形式に終端を置きそれ以外では置かないため,複雑な方法を使用する ことから免除されます.

一つの引数を用いた丸カッコ相互参照は以下のようになります.

 
... storms cause flooding (@pxref{Hurricanes}) ...

それは,以下を生成します.

 
... storms cause flooding (*Note Hurricanes::) ...

そして,以下を生成します.

... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...

二つの引数を用いた丸カッコ相互参照は,以下のようなテンプレートになります.

 
... (@pxref{node-name, cross-reference-name}) ...

それは,以下を生成します.

 
... (*Note cross-reference-name: node-name.) ...

そして,以下を生成します.

... (see Section nnn [node-name], page ppp) ...

@pxref@xrefのように,最大五つの引数を使用することが可能 です(@xref{xref, , @xref}).

注意してください:@pxrefは,丸カッコの参照としてのみ使用 してください.@pxrefを文の文節として使用しようとしないでください. それは,Infoファイル,印刷物,またはその両方で悪く見えます.

また,丸カッコ相互参照は文の終りでも最善のようです.文中に書くこともでき ますが,その場所はテキストの流れを分断します.


8.6 @inforef

@inforefは印刷されたマニュアルには無い,Infoファイルへの相互参照 に対して使用されます.印刷されたマニュアルでも,@inforefはInfo ファイルでユーザが見えるような参照を生成します.

このコマンドは,以下の順番で二つまたは三つの引数をとります.

  1. ノード名.

  2. 相互参照名(オプション).

  3. Infoファイル名.

@xrefのように引数はカンマで分けられます.また,@xrefのよ うに`}'の後でカンマやピリオドで参照を終端する必要もあります.

テンプレートは以下のようになります.

 
@inforef{node-name, cross-reference-name, info-file-name},

以下のようにします.

 
@inforef{Expert, Advanced Info commands, info},
for more information.

以下を生成します.

 
*Note Advanced Info commands: (info)Expert,
for more information.

そして,以下を生成します.

See Info file `info', node `Expert', for more information.

同様に,以下のようにします.

 
@inforef{Expert, , info}, for more information.

以下を生成します.

 
*Note (info)Expert::, for more information.

そして,以下を生成します.

See Info file `info', node `Expert', for more information.

@inforefの逆は@citeで,それはInfo形式がない印刷物を参照 するために使用します.See section @cite.


8.7 @uref{url[, text][, replacement]}

@urefは,ユニフォームリソースロケータ(url)への参照を生成します. それは,一つの必須の引数urlと表示されるテキストを制御する二つの追加の引数 をとります.HTML出力では,@urefはたどることが可能なリンクを生成 します.

二番目の引数が指定されている場合,それは表示するテキストです(デフォルトは url自身です).InfoとDVI出力ではurlも出力され,HTML出力ではそうなりません.

一方,三番目の引数が指定されている場合もテキストは表示されますが,urlは全 ての書式で出力されません.これは,テキストがmanページのように既に 十分参考にされているとき役に立ちます.三番目の引数が与えられた場合,二番目 の引数は無視されます.

簡単な一つの引数の形式では,urlはターゲットとリンクのテキストの両方になり ます.

 
The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.

以下を生成します.

 
The official GNU ftp site is ftp://ftp.gnu.org/gnu.

二つの引数の形式の例です.

 
The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
holds programs and texts.

以下を生成します.

 
The official GNU ftp site
holds programs and texts.

そして,Info出力はこのようになります.

 
The official GNU ftp site (ftp://ftp.gnu.org/gnu)
holds programs and texts.

HTML出力はこのようになります.

 
The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
holds programs and texts.

三つの引数の形式の例です.

 
The @uref{/man.cgi/1/ls,,ls(1)} program ...

以下を生成します.

 
The ls(1) program ...

しかしHTMLでは,以下のようになります.

 
The <a href="/man.cgi/1/ls">ls(1)</a> program ...

人々がたどることが可能なリンクを作成せず,単にurlを示すため, @urlを使用してください(see section @url).

urlの明確な書式を表示することを好む人もいます.

 
<URL:http://host/path>

好みにより,この形式を入力ファイルで使用することも可能です.テキストから urlの検出を試みるあらゆるソフトウェアでは,便利にするために, `<URL:'無しで検出する必要があるので,我々は余分な`<URL:'と `>'を用い,出力をバラバラにすることは必要ないと思います.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Akihiro Sagawa on January, 21 2003 using texi2html