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

6. ノード

ノード(Nodes)はTexinfoファイルの主要な部分です．それらは，それ自身 が階層的ではなく，ファイル構造でもありません．ノードは，他のノードの名前 を持つノードポインタ(node pointers)を含み，ノードをリストアップし ているメニュー(menus) を含めることも可能です．Infoでは，移動コマン ドで指示されたノードやメニューのノードリストへ移動することが可能です．ノー ドポインタとメニューは，Info ファイルに，章，セクション，サブセクション 等のような構造を提供していて，それらは印刷された本に構造を提供しているも のに似ています．

6.1 二つのパス  Different commands to structure Info output and printed output.
6.2 ノードとメニューの図  A diagram, and sample nodes and menus.
6.3 @nodeコマンド  Creating nodes, in detail.
6.4 makeinfoでポインタを作成する  Letting makeinfo determine node pointers.
6.5 @anchor:相互参照のターゲット任意に定義する  Defining arbitrary cross-reference targets.

6.1 二つのパス

ノードとメニューコマンドと章の構造化コマンドは，専門的にはお互い独立して います．

ノードポインタとメニューを，Infoファイルを好きなように構造化するために使 用することが可能です．Texinfoファイルで，Info出力が印刷物と異なるように 書くことも可能です．しかし，ほとんど全てのTexinfoファイルは，Info出力の 構造が印刷物の構造に対応するように書かれています．そうしなければ，読者は 不便で理解不能になります．

一般に，印刷物は章が主要な大枝でそこからセクションが枝を出している木のよ うな階層構造です．同様に，ノードポインタとメニューは，Info出力で一致する 構造を作成するように組織化されています．

6.2 ノードとメニューの図

前で示した，章が三つでそれぞれが二つのセクションを含むTexinfoファイル図 の，コピーは以下のようになります．

"root"は図の最上部で，"leaves"が最下部です．これはそのような図を書く 慣習的な方法です．それは，さかさまの木を描きます．このため，ルートノード は`Top'ノードと呼ばれ，`Up'ノードはルートに近い方向へ導きます．

 
                                  Top
                                   |
             ---------------------------------------------
            |                      |                      |
           1 章                   2 章                   3 章
            |                      |                      |
       -----------            -----------            -----------
      |           |          |           |          |           |
 セクション  セクション セクション  セクション セクション  セクション
     1.1         1.2        2.1         2.2        3.1         3.2

二章を開始するため，完全に書かれたコマンドは以下のようになります．

 
@node     Chapter 2,  Chapter 3, Chapter 1, Top
@comment  node-name,  next,      previous,  up

この@node行は，このノード名が"Chapter 2"で，`Next'ノードが "Chapter 3"で，`Previous'ノードが"Chapter 1"で，`Up'ノードが"Top" だということを告げています．ドキュメントが階層的に組織化されている場合 (see section 6.4 makeinfoでポインタを作成する)，これらのノード名を書くことを省略可 能ですが，ポインタの関係は得られます．

注意してください:`Next'は，マニュアルで同じ階層レベルの次のノー ドを参照し，それは，Texinfoファイル内での次のノードである必要はありませ ん．Texinfoファイルでは，次のノードは下のレベルかもしません -- 例えば， セクションレベルノードは，章レベルのノードに続くことが多くあります． `Next' と`Previous'は，同じ階層レベルのノードを参照します．(`Top' ノードはこの規則の例外です．`Top'ノードはそのレベルでの唯一のノードなの で，`Next'は，以下にある最初のノードを参照し，それは通常，章や章レベルの ノードです．)

Infoを使用して，セクション2.1と2.2に行くため，2章の内部にメニューが必要 です．(See section 7. メニュー.)以下のように，セクション2.1をはじめる前に，メニュー を書きます．

 
   @menu
   * Sect. 2.1::    Description of this section.
   * Sect. 2.2::
   @end menu

セクション2.1に対して，以下のように書いてください．

 
   @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
   @comment  node-name, next,      previous,  up

Info書式では，ノードの`Next'と`Previous'ポインタは通常，同じレベルの他の ノードへ導きます -- 章から章や，セクションからセクションのようになりま す(ここまで見てきたように，`Previous'ポインタが上を指すこともあります)． `Up'ポインタは通常，上のレベルのノードへ導きます(`Top'ノードに近い方向で す)．`Menu'は下のレベルのノードへ導きます(`leaves'に近い方向です)．(相互 参照は，あらゆるレベルのノードを指し示します．8. 相互参照を参 照してください．)

通常，@nodeコマンドと章の構造化コマンドは，索引コマンドと一緒に 順番に使用されます．(@node行に，指し示すものを覚えておくためのコ メント行を続けてもかまいません．)

このマニュアルの"Ending a Texinfo File"と呼ばれる章の最初は以下のよう になっています．これには，@node行，それに続くコメント行， @chapter行，そして索引行があります．

 
@node    Ending a File, Structuring, Beginning a File, Top
@comment node-name,     next,        previous,         up
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending

6.3 @nodeコマンド

ノード(node)とは，@nodeコマンドで始まり，次の@node コマンドまで続くテキストの塊です．ノードの定義は章やセクションとは異なり ます．章にセクションを含めてもかまいませんし，セクションにサブセクション を含めてもかまいません．しかし，ノードにサブノードを含めることは不可能で す．ノードのテキストは，ファイルの次の@nodeコマンドまで続くだけ です．ノードは通常，章の構造化コマンドを一つだけ含み，それは @node行に続けます．一方，印刷物ではノードは相互参照としてのみ使 用されるので，章やセクションに複数のノードを含めてもかまいません．実際， 章は通常，それぞれのセクション，サブセクション，そしてサブサブセクション となる複数のノードを含んでいます．

ノードを作成するため，@nodeコマンドを行の最初に書き，カンマで分 離した四つの引数を同じ行の残りに続けてください．最初の引数は必要です．そ れはノードの名前です．次の引数は，順番で，`Next'，`Previous'，そして`Up' ポインタの名前で，Texinfoドキュメントが階層的に組織化されている場合，省 略可能です(see section 6.4 makeinfoでポインタを作成する)．

好みにより，それぞれの名前の前にスペースを挿入してもかまいません．スペー スは無視されます．ノードの名前と，(存在する場合は)`Next'，`Previous'，そ して`Up'ポインタの名前をすべて同じ行に書く必要があります．そうしない場合， 書式化は失敗します．(Infoのノードの詳細は，See Info file `info-ja', node `Top'.)

通常，章の構造化コマンド行を@nodeの直後に書き，例えば，それは @sectionや@subsectionです．(See section 5.2 構造化コマンドの形式.)

注意してください:GNU Emacs Texinfoモードの更新コマンドは， @node行が章の構造化コマンドに続いているTexinfoファイルでのみ動作 します．See section 2.4.1 更新の必要条件.

TeXでは，相互参照で使用する名前を識別するために@node行を使用 します．このため，@node行を印刷のための書式化を行いたいTexinfo ファイルに，たとえInfoで書式化するつもりがなくても書く必要があります． (相互参照は，この文章の終りにあるようなもので，@xrefとそれに関連 するコマンドで作成されます．8. 相互参照を参照してください．)

6.3.1 ノードとポインタの名前の選択  How to choose node and pointer names.
6.3.2 @node行の書き方  How to write an @node line.
6.3.3 @node行の助言  Keep names short.
6.3.4 @node行の必要事項  Keep names unique, without @-commands.
6.3.5 最初のノード  How to write a `Top' node.
6.3.6 @topセクションコマンド  How to use the @top command.

6.3.1 ノードとポインタの名前の選択

ノード名はノードの識別子です．ポインタで他のノードに行くことが可能で，そ れは単純にこれらのノード名から成り立っています．

通常，ノードの`Up'ポインタは，そのノードを記述しているメニューがあるノー ドの名前を含みます．ノードの`Next'ポインタは，メニューでそのノードの次の ノード名を含み，`Previous'ポインタは，メニューでそのノードの前のノード名 を含みます．ノードの`Previous'ノードが`Up'ノードと同じとき，両方のノード は同じノード名を示します．

通常，Texinfoファイルの最初のノードは`Top'ノードで，その`Up'と`Previous' ポインタは`dir'ファイルを指し示し，それはInfo全てのメインメニューを 含んでいます．

`Top'ノード自身は，マニュアルのメインまたはマスターメニューを含みます． また，`Top'ノードに簡単なマニュアルの記述を含めると役に立ちます．Texinfo ファイルの最初のノードの書き方の詳細は，See section 6.3.5 最初のノード.

明示的に全てのポインタを指定したときでも，任意の順番でTexinfoソースファ イルにノードを書くことができるということを意味するわけではありません！ TeXは，ノードポインタにかかわらずファイルを順番に処理するので，印刷物 に現したい順番にノードを書く必要があります．

6.3.2 @node行の書き方

@node行の最も簡単な書き方は，@nodeを行の最初に書き，その 後にノード名を以下のように書く方法です．

 
@node node-name

GNU Emacsを使用している場合，ポインタ名を挿入するために，Texinfoモードで ノードの更新コマンドが提供されています．また，ポインタをTexinfoファイル の外に置き，makeinfoでノードポインタを作成するInfoファイルに挿入 することも可能です．(See section 2. Texinfoモードを使用する. また6.4 makeinfoでポインタを作成するを参照してください．)

代わりに，`Next'，`Previous'，そして`Up'ポインタを独自に挿入することも可 能です．こうする場合，TexinfoモードでキーボードコマンドのC-c C-c n を使用すると便利だと思います．このコマンドは，`@node'と，適切な順 番でポインタ名をリストアップしたコメント行を挿入します．コメント行は，引 数がどのポインタに対するものかを，追跡記録するのに役立ちます．このコメン ト行は，Texinfoに精通していない場合，特に便利です．

`Next'，`Previous'，そして`Up'ポインタがある，完全に書かれたノード行のテ ンプレートは以下のようになります．

 
@node node-name, next, previous, up

希望があれば，初稿では@node行を完全に無視することが可能で，その 後でtexinfo-insert-node-linesコマンドを@node行を作成する ために使用してください．しかし，この方法はお勧めしません．その部分を書く と同時にそれ自身のノードに名前を付ける方が良く，そうすることで相互参照を 作成しやすくなります．相互参照が多数あることは，良いInfoファイルの特徴と して特に重要です．

@node行を挿入した後，すぐに@-コマンドを章やセクションに対し書き， 名前を挿入するべきです．次に(これが肝心！)，いくつかの索引項目を書いてく ださい．通常，少なくとも二つ書き，索引でノードを参照する方法として，四つ または五つあることもよくあります．これで，人々がノードをより容易に見つけ られるようになります．

6.3.3 @node行の助言

ここに三つの提案があります．

6.3.4 @node行の必要事項

@node行でいくつかある必要事項は以下のようなものです．

6.3.5 最初のノード

Texinfoファイルの最初のノードは，インクルードファイルは例外として (see section D. インクルードファイル)，トップ(Top)ノードです．トップノードには， ドキュメントの短い概要，コピーの許可，そしてマスターメニューを含めるべき です．Topノードの内容と例の詳細は，See section 3.5 `Top'ノードとマスターメニュー.

Topノードで使用されているノードポインタの記述は以下のようになります．

Infoファイルの`info'ディレクトリへのインストールの詳細は， See section 20.2 Infoファイルのインストール.

具体的には，明示的なポインタを示す例は以下のようになります(texinfoモード のコマンドで自動的に管理することが可能です)．

または，ポインタを完全に無くし，ツールに暗黙的に定義させることも可能です． これは推奨されます．このため以下のようにします．

 
@node Top

6.3.6 @topセクションコマンド

特別なセクションコマンド@topは，@node Top行とともに使用 すべきです．@topセクションコマンドは，それがファイルの`Top'ノー ドだという印を付けるようmakeinfoに伝えます．それは，ノードポイン タを自動的に挿入するためにmakeinfoが必要とする情報を提供します． @topコマンドを行の最初に書き，直後に@node Top行を続けて ください．@topコマンドと同じ行の残りの部分にタイトルを書いてくだ さい．

Infoでは，@topセクションコマンドは，タイトルが単独行に現れるよう にし，他のセクションコマンドと同様にアスタリスクを下に挿入します．

TeXとtexinfo-format-bufferでは，@topセクションコマンド は@unnumberedとほとんど同義語です．これらのフォーマッタは， @topコマンドを要求せず，特別なことは何もしません．これらのフォー マッタを使用するとき，@chapterや@unnumberedを @node Top行の後に使用することも可能です．また，ポインタとメニュー を作成更新するため，Texinfo更新コマンドを使用する時に@chapterや @unnumberedを使用することも可能です．

このため，具体的には，Topノードは以下のようにして開始します．

 
@node Top
@top Your Manual Title

6.4 makeinfoでポインタを作成する

makeinfoプログラムは，階層的に組織化されているファイルに対し，自 動的にノードポインタを定義する機能があります．

この機能を利用するとき，`Next'，`Previous'，そして`Up'ポインタを，ノード 名の後に書く必要がありません．しかし，@chapterや@section のようなセクションコマンドを，それぞれの切り詰めた@node行の直後 の行に書く必要があります(例外は，コメント行が間に入ることです)．

さらに，`Top'@node行に，ファイルの`Top'ノードに印を付ける @topで始まる行を続ける必要があります．See section @top.

最後に，(`Top'ノード以外の)それぞれのノード名を，ノードの階層レベルの上 に，一つかそれ以上の階層レベルとなるメニューに書く必要があります．

このmakeinfoのノードポインタ挿入の機能は，手動やTexinfoモードのコ マンドでメニューやポインタを更新する必要から開放します．(See section 2.4 ノードとメニューの更新.)

ほとんどの状況で，この機能の利点を利用し，冗長にノードポインタを指定した くはないでしょう．しかし，Texinfoドキュメントは，階層的に組織化されてい ることや実際にセクションコマンドが完全に含まれていることを要求していませ ん．例えば，印刷を目的としていないドキュメントの場合です．これらの状況で は，明示的にポインタを指定する必要があります．

6.5 @anchor:相互参照のターゲット任意に定義する

アンカー(anchor)は，相互参照が参照可能な，まるでノードのようなドキュ メント内の位置です．@anchorコマンドでアンカーを作成し，普通のカッ コで分離された引数としてラベルを与えます．例えば，以下のようになります．

 
This marks the @anchor{x-spot}spot.
...
@xref{x-spot,,the spot}.

以下を生成します．

 
This marks the spot.
...
See [the spot], page 1.

御覧のように，@anchorコマンド自身は出力を生成しません．この例は アンカー`x-spot'だけを，単語`スポット'の直前に定義します．その後で，後述 の@xrefや，その他の相互参照を使用して参照することが可能になりま す．相互参照の詳細は，See section 8. 相互参照.

@anchorコマンドを参照する位置の直前に置くのが最善です．そうする ことで，読者の目はアンカーにジャンプしたとき正しいテキストに導かれます． @anchorコマンドを単独行に置くことでソースの可読性が改善される場 合は，そうすることもできます．@anchor後のスペースは常に無視され ます．

アンカー名とノード名は衝突してはいけません．アンカーとノードは同じように 扱われることもあります．例えば，スタンドアローンInfoのgoto-nodeコ マンドは，アンカー名やノード名を引数としてとります． (See section `goto-node' in GNU Info.)

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

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