[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
相互参照(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. |
いつもではありませんが,ほとんどの印刷されたドキュメントは順番に読むよう に設計されています.人々は,必要なとき提出されるべき情報を見つけるために, 前後にページをめくるのが嫌になります.
しかしドキュメントには,現在の文脈に対しては詳しすぎたり主要でなかったり する情報もあります.そのような情報へのアクセスを提供するため相互参照を使 用してください.また,オンラインヘルプシステムやリファレンスマニュアルは. 小説とは異なります.そのようなドキュメントを最初から最後まで順番に読む人 はほとんどいません.代わりに,人々は必要なところを拾い読みします.このた め,そのようなものでは,読者が読まなかった可能性のある他の情報を見つける とき役に立つ相互参照を多く含めるべきです.
印刷されたマニュアルでは,完全に他のマニュアルでない限り,相互参照は結果 としてページ参照となり,他のマニュアルの場合は相互参照はマニュアルの名前 になります.
Infoでは,相互参照は結果としてInfoの`f'コマンドに続いて使用可能な項 目となります.(See Info file `info', node `Help-Adv'.)
様々な相互参照コマンドは,ノード(やアンカー
see section @anchor
)を相互参照の位置を定義するために使用しま
す.これはInfoの環境の話で,そこでの相互参照は指定した場所に移動します.
TeXもノードを相互参照の位置を定義するために使用しますが,動作は明白で
はありません.TeXがDVIファイルを生成するとき,それは,それぞれのノー
ドのページを記録し参照を作成する際にページ番号を使用します.このため,印
刷されるだけのマニュアルを書くだけでオンラインで使用しない場合でさえ,相
互参照する場所に名前をつけるために@node
行を書く必要があります.
四つの様々な相互参照のコマンドがあります.
@xref
@ref
@xref
と同じです.印刷さ
れたマニュアルでは参照だけを生成し,前に`See'を生成しません.
@pxref
@inforef
(@cite
コマンドは,Infoと関係の無い本やマニュアルへの参照を作成す
るために使用され,それゆえ,指し示すノードはありません.See section @cite
.)
相互参照のコマンドは一つの引数のみを要求し,それは参照するノード名です. しかし,相互参照コマンドは四つの追加の引数を含むことができます.これらの 引数を使用することで,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.
印刷された本ではこうなります.
相互参照に対する五つの利用可能な引数は,以下の通りです.
完全な五つの引数を持つ相互参照のテンプレートは,以下のようになります.
@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
はカッコ内に,カンマで分けられたいくつかの引数が続きます.
これらのカンマの前後の空白は無視されます.
相互参照はノード名のみ必要です.しかし,それは最大四つまで追加引数を含む ことができます.これらの変数はそれぞれ,幾分異なるように見える相互参照を 生成します.
注意してください:カンマは相互参照で引数を分離します.フォーマッ タがそれらをセパレータと間違えないように,タイトルや他の部分にそれらを含 めるのを避けてください.
@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.
(前の例では,閉じカッコはカンマと文節が続き,それにはピリオドが続くこと に注意してください.)
@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.
(前の例では,閉じカッコはカンマと文節が続き,それにはピリオドが続くことに 注意してください.)
三番目の引数は,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}. |
@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ファイルを作成するときです.こ の場合,四番目の引数のみを指定し,五番目はその必要がありません.
相互参照では,常にノードを名付ける必要があります.これは,マニュアル全体
を参照するために,@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'がマニュアルの 最初のセクション名です.
@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出力 でも最善に見えます.
@pxref
丸カッコの参照コマンド@pxref
は,@xref
とほとんど同じです
が,丸カッコの中でのみ使用し,コマンドの閉じカッコの後にカンマや
ピリオドを入力しません.コマンドは二つの点で@xref
と異なり
ます.
書式化の一つの形式は自動的に閉じる句読点を挿入し,もう一つはそうしないの
で,@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ファイル,印刷物,またはその両方で悪く見えます.また,丸カッコ相互参照は文の終りでも最善のようです.文中に書くこともでき ますが,その場所はテキストの流れを分断します.
@inforef
@inforef
は印刷されたマニュアルには無い,Infoファイルへの相互参照
に対して使用されます.印刷されたマニュアルでも,@inforef
は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
.
@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] | [ ? ] |