| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
ドキュメントの内容のミス以外に，Texinfoで犯すミスは二種類あるはずです． @-コマンドでミスを犯し，ノードと章の構造でミスを犯します．
Emacsには@-コマンドのミスを捕らえる二つのツールと，構造のミスを捕らえる 二つの方法があります．
@-コマンドの問題を見つけるため，問題の有る領域でTeXや領域の書式化コ マンドを実行することが可能です．これらのコマンドを，書いているときにそれ ぞれの領域で本当に実行することが可能です．
ノードと章の構造の問題を見つけるため，C-c C-s
(texinfo-show-structure)に関連するoccurコマンドを使用する
ことが可能で，そして，M-x Info-validateを使用することが可能です．
makeinfo Find Errors | makeinfo finds errors. | |
| F.1 Infoの書式化でエラーを捕らえる | How to catch errors with Info formatting. | |
| F.2 TeX書式化でエラーを捕らえる | How to catch errors with TeX formatting. | |
F.3 texinfo-show-structureの使用 | How to use texinfo-show-structure. | |
F.4 occurの使用 | How to list all lines containing a pattern. | |
| F.5 悪いノード参照を見つける | How to find badly referenced nodes. |
makeinfo Find Errors makeinfoが見つけるエラー
makeinfoプログラムはエラーを捕らえそれらを報告する優れた仕事を行
います -- texinfo-format-regionやtexinfo-format-bufferよ
り遥かに優れています．さらに，自動的にノードポインタとメニューを作成更新
する様々な機能は，ヒューマンエラーの発生の多くを取り除きます．
ポインタとメニューを作成したり挿入したりする更新コマンドを，できる限り使
用してください．そして，makeinfo(または，Texinfoモードの表現の
makeinfo-regionとmakeinfo-buffer)を，ファイルを書式化した
り他のエラーを調べるために使用してください．これは，Texinfoで仕事をする
ための最善の方法です．しかし，makeinfoを使用できない，または，問
題が大変難問な場合，この付録で記述されているツールを使用したいと思うかも
しれません．
Texinfoファイルの一部を書いた後，領域の書式化が正確かどうかを見るために，
texinfo-format-regionやmakeinfo-regionコマンドを使用するこ
とが可能です．
しかしほとんどの場合，とある理由でmakeinfo-regionコマンドが使えな
いためにこのセクションを読んでいることでしょう．それゆえ，このセクション
の残りは，texinfo-format-regionの使用を想定します．
@-コマンドでミスを犯した場合，texinfo-format-regionはエラー時ま
たはその後で処理を停止し，エラーメッセージを表示します．エラーが発生した
バッファを見るために，`*Info Region*'バッファに切替えてください．カー
ソルはエラーの位置の後にあります．また，エラーが発生した(または，より正
確にはそれが検出された)後，テキストは書式化されません．
例えば偶然，@end menuの代わりに最後に`s'が付いたコマンド
@end menusでメニューを終了した場合，以下のようなエラーメッセージ
を得るでしょう．
@end menus is not handled by texinfo |
カーソルはバッファ内の，エラーが発生した場所やそこからそう遠くない場所で 止まります．バッファは以下のようになります．
---------- Buffer: *Info Region* ----------
* Menu:
* Using texinfo-show-structure:: How to use
`texinfo-show-structure'
to catch mistakes.
* Running Info-Validate:: How to check for
unreferenced nodes.
@end menus
-!-
---------- Buffer: *Info Region* ----------
|
texinfo-format-regionコマンドは，ちょっと変わったエラーメッセージ
を提供することもあります．例えば，書式化で相互参照の追跡で失敗したとしま
す．
(@xref{Catching Mistakes, for more info.)
|
この場合，texinfo-format-regionは，足りない閉じカッコを検出してい
ますが，メッセージは，`Unbalanced braces'ではなく`Unbalanced
parentheses'になります．これは，書式化コマンドが弓カッコの不一致を，それ
があたかもカッコであるかのように探すためです．
texinfo-format-regionはミスの検出に失敗するときもあります．例えば，
以下では，閉じカッコと閉じ弓カッコが置き換わっています．
(@xref{Catching Mistakes), for more info.}
|
書式化では以下を生成します．
(*Note for more info.: Catching Mistakes) |
このエラーを検出する唯一の方法は，以下のように参照を実現することです．
(*Note Catching Mistakes::, for more info.) |
ついでに，Infoでこのノードを読んでいて，f RET
(Info-follow-reference)を入力した場合，以下のエラーメッセージを生
成するでしょう．
No such node: "Catching Mistakes) The only way ... |
これは，Infoがエラーの例を，このノードの最初の相互参照として提供するため
で，Infoのfコマンドの直後にRETを入力した場合，Infoは参照ノー
ドに行こうと試みるでしょう．f catch TAB RETと入力した
場合，Infoは正確に書かれている例のノード名を認知し，`Catching Mistakes'
ノードへ連れて行くでしょう．(これを試みる場合，l(Info-last)
を入力し，`Catching Mistakes'に戻ることができます．)
TeXでファイルを書式化しているときにミスを捕らえることも可能です．
通常，texinfo-format-bufferは，TeXより有意義なエラーメッセージ
を表示するときもあるので，同じファイルでtexinfo-format-buffer(や，
それより良いmakeinfo-buffer)を実行後にこうしたいと思うことでしょ
う．(See section F.1 Infoの書式化でエラーを捕らえる, for more information.)
例えば，TexinfoファイルでTeXを実行した時の一部を以下に示します．
---------- Buffer: texinfo.texi ----------
name of the Texinfo file as an extension. The
@samp{??} are `wildcards' that cause the shell to
substitute all the raw index files. (@xref{sorting
indices, for more information about sorting
indices.)@refill
---------- Buffer: texinfo.texi ----------
|
(相互参照に閉じカッコがありません．)TeXは停止した後，以下の出力を生成 します．
---------- Buffer: *tex-shell* ----------
Runaway argument?
{sorting indices, for more information about sorting
indices.) @refill @ETC.
! Paragraph ended before @xref was complete.
<to be read again>
@par
l.27
?
---------- Buffer: *tex-shell* ----------
|
この状況では，TeXは正確で理解可能なエラーメッセージを生成しました．
Paragraph ended before @xref was complete. |
`@par'は，Texinfoと関係が無いTeXの内部コマンドです．`l.27' は，TeXが問題をTexinfoファイルの27行で検出したという意味です． `?'は，この状況でTeXが使用するプロンプトです．
残念ながらTeXは常に役に立つ訳ではなく，間違ったものを発見するために， 本当にシャーロック ホームズになる必要があります．
いずれにせよ，このような問題に遭遇した場合，三つのことを行うことが可能で す．
これは最善のことが多くなっています．しかし，用心してください．その結果が ファイルの残り全体となるように考え，一つのエラーが更なるエラーメッセージ として連続して生成される可能性が有ります．そのようなエラーメッセージの雪 崩を生成している時にTeXを止めるため，C-c(または，Emacsの内部シェ ルで実行している場合はC-c C-c)を入力してください．
Emacs内部でTeXを実行している場合，シェルバッファとTeXが`?'プ ロンプトを出している行を切替える必要があります．
TeXは，問題があってもエラーメッセージを生成せずにファイルを書式化する
ときもあります．これは通常，コマンドが終っていないがTeXは処理を続けら
れる場合に生じます．例えば，@end itemizeコマンドで項目分けリスト
を終了するのに失敗した場合，TeXは印刷出力可能なDVIファイルを書き出し
ます．TeXが与えるエラーメッセージは幾分不可思議な以下のようなコメント
だけです．
(@end occurred inside a group at level 1) |
しかし，DVIファイルを印刷した場合，項目分けリストに続くファイルのテキス
トが，項目分けリストの最後の項目の部分であるかのように全部字下げされてい
ることが分かります．エラーメッセージは，TeXがファイルで@end
コマンドを見つかることを期待していたが，必要とされる場所を特定できなかっ
たということです．
エラーが見つけにくいと悪名高いもう一つのソースは，@end groupコマ
ンドが無いことです．理解できないエラーで困惑している場合，最初に
@end groupコマンドが無いものを探してください．
Texinfoファイルにヘッダが足りない場合，TeXは実行の最初で停止し，以下 のような出力を表示します．`*'はTeXが入力を待っていることを示して います．
This is TeX, Version 3.14159 (Web2c 7.0) (test.texinfo [1]) * |
この状況では，アスタリスクの後で\end RETを単純に入力してくだ さい．そして，Texinfoファイルのヘッダ行を書き，もう一度TeXコマンドを 実行してください．(バックスラッシュ`\'の使用に注意してください． TeXは`@'の代わりに`\'を使用します．そしてこの状況では， Texinfoではなく直接TeXで作業しているのです．)
texinfo-show-structureの使用 Texinfoファイルの，ノード，章，セクション，そしてサブセクションの記録追 跡は，常に簡単なわけではありません．これは，他人が書いたTexinfoファイル を修正追加している場合は，特に真になります．
GNU EmacsのTexinfoモードでは，texinfo-show-structureコマンドは，
構造を指定する@-コマンドで始まる全ての行をリストアップします．
@chapter，@section，@appendix等です．引数(対話的
な場合は，前置引数C-u)を用いることで，コマンドは@node
行も表示します．texinfo-show-structureコマンドは，Texinfoモードで
C-c C-sに，デフォルトでバインドされています．
行は，`*Occur*'と呼ばれるバッファに，階層レベルで字下げされて表示さ
れます．例えば以下は，このマニュアルでのtexinfo-show-structureを
実行したものが生成したものの一部になります．
Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
in buffer texinfo.texi.
...
4177:@chapter Nodes
4198: @heading Two Paths
4231: @section Node and Menu Illustration
4337: @section The @code{@@node} Command
4393: @subheading Choosing Node and Pointer Names
4417: @subsection How to Write an @code{@@node} Line
4469: @subsection @code{@@node} Line Tips
...
|
これは，`texinfo.txi'ファイルの4337，4393，そして4417行が，それぞれ
@section，@subheading，そして@subsectionで始まっ
ていることを告げています．カーソルを`*Occur*'ウィンドウに移動した場
合，Texinfoファイルで対応する場所にジャンプするため，行の一つにカーソル
を置き，C-c C-cコマンド(occur-mode-goto-occurrence)を使用す
ることで可能となります．occur-mode-goto-occurrenceに関する詳細は，
See section `Using Occur' in The GNU Emacs Manual.
`*Occur*'ウィンドウの最初の行は，texinfo-heading-patternで指
定された正規表現(regular expression)の記述です．この正規表現は，
texinfo-show-structureが探すパターンです．詳細は，See section `Using Regular Expressions' in The GNU Emacs Manual.
texinfo-show-structureコマンドを呼び出すとき，Emacsはバッファ全体
の構造を表示します．バッファの一部のみ，例えば一つの章の構造を見たい場合，
領域をマークするためC-x n n (narrow-to-region)コマンドを使
用してください．(See section `Narrowing' in The GNU Emacs Manual.)これ
は，上記の生成で使用された例の方法です．(再びバッファ全体を見るため，
C-x n w (widen)を使用してください．)
C-u C-c C-sと入力して，前置引数を用いて
texinfo-show-structureを呼び出す場合，@chapter，
@sectionのような@-サインコマンドで始まる行と同様に，
@nodeで始まる行をリストアップします．
`*Occur*'ウィンドウのリストを見ることで，Texinfoファイルの構造を思 い出すことが可能です．そして，間違った名前のノードや飛ばしたセクションが ある場合，ミスを修正することが可能です．
occurの使用
texinfo-show-structureコマンドが，余りに多い情報を生成するときも
あります．おそらく，Texinfoファイルの全体的な構造を思い出したいとき，
texinfo-show-structureが生成した詳細なリストに圧倒されます．この
状況では，occurコマンドを直接使用することが可能です．こうするため，
以下のように入力します．
M-x occur |
その後で，regexpの形式で入力を促されたとき，一致させたいパターンの
正規表現を入力してください．(See section `Regular Expressions' in The GNU Emacs Manual.)occurコマンドは，バッファの現在のカー
ソル位置からバッファの終りまで作用します．バッファ全体でoccurを実
行したい場合，カーソルをバッファの最初に置いてください．
例えば，行の中に`@chapter'を含む全ての行を見たい場合， `@chapter'を入力してください．これは章のリストを生成します．それは， 行の真中に`@chapter'がある文も全てリストアップします．
単語`@chapter'で始まるこれらの行のみを見たい場合，occurで入
力を促されたとき，`^@chapter'を入力してください．単語や文節で終る
全ての行を見たい場合，例えば`catching mistakes$'のように，`$'
で単語の終りを終えてください．これは，同じ章やセクションの一部や，その理
由から同じ`Up'ポインタを持っている全てのノードを見たいとき役に立つはずで
す．
詳細は，See section `Using Occur' in The GNU Emacs Manual.
あらゆる`Next'，`Previous'，`Up'やその他のノードポインタがノードを指し示
すことに失敗しているかどうかを調査するため，Info-validateを使用す
ることが可能です．このコマンドは，全てのノードポインタが存在するノードを
指し示していることを調べます．Info-validateコマンドは，Texinfoファ
イルではなくInfoファイルでのみ動作します．
makeinfoプログラムは自動的にポインタの有効の調査を行うので，
makeinfoを使用している場合，Info-validateを使用する必要は
ありません．makeinfoが実行不可能で，その代わりに
texinfo-format-regionやtexinfo-format-bufferを使用している
場合や，スクラッチからInfoファイルを書く場合のみ，Info-validateを
使用する必要があります．
F.5.1 Info-validateの実行 | How to run Info-validate. | |
| F.5.2 分割されないファイルの作成 | How to create an unsplit file. | |
| F.5.3 ファイルのタグ付け | How to tagify a file. | |
| F.5.4 ファイルを手動で分割 | How to split a file manually. |
Info-validateの実行
Info-validateを使用するため，調査したいInfoファイルに移動し，以下
を入力してください．
M-x Info-validate |
Info-validateコマンドは大文字の`I'が要求されることに注意してくだ
さい．また，Info-validateを実行する前にタグ表を作成する必要がある
かもしれません．See section F.5.3 ファイルのタグ付け.
ファイルが有効な場合，"File appears valid"というメッセージを受け取りま す．しかし，ノードを指し示さないポインタがある場合，`*problems in info file*'と呼ばれるバッファにエラーメッセージが表示されます．
例えば，Info-validateは，このマニュアルの最初のノードのみを含むテ
ストファイルで実行されたとします．メッセージの一つは以下のようになります．
In node "Overview", invalid Next: Texinfo Mode |
この意味は，`Overview'と呼ばれるノードに何も指し示さない`Next'ポイ ンタがあるということを意味します(テストファイルには一つのノードしかない ので，この場合はそうなります．)．
さて，我々が`Texinfo Mode'という名のノードをテストケースに加えます が，このノードの`Previous'を指定しないとします．そのとき我々は以下のよう なエラーメッセージを得ます．
In node "Texinfo Mode", should have Previous: Overview |
これは，全ての`Next'ポインタは，戻るための(`Next'を示すノードにある) `Previous'に一致すべきだからです．
Info-validateは，全てのメニュー項目と相互参照が実際にノードを指し
示していることも調査します．
Info-validateはタグ表が必要で，分割されたファイルでは動作しません．
(texinfo-format-bufferコマンドは，大きなファイルを自動的に分割し
ます．)大きなファイルでInfo-validateを使用するため，Infoファイル
が分割されないように，引数を用いてtexinfo-format-bufferを実行する
必要があります．そして，分割されていないファイルのためタグ表を作成する必
要があります．
Info-validateは，タグ表を持った単一のInfoファイルのでのみ実行可能
です．コマンドは，マスターファイルが分割されたとき生成されたサブファイル
では，間接的に動作しません．(70,000バイトかそれくらい以上の)大きなファイ
ルがある場合，間接的なサブファイルを生成しないような方法で
texinfo-format-bufferやmakeinfo-bufferコマンドを実行する必
要があります．Infoファイルのためのタグ表も作成する必要があります．これを
行った後でInfo-validateを実行し，悪い参照ノードを探すことが可能に
なります．
第一段階は分割されないInfoファイルを作成することです．
texinfo-format-bufferがTexinfoファイルをより小さなInfoファイルに
分割することを避けるため，M-x texinfo-format-bufferコマンドに前置
引数を与えてください．
C-u M-x texinfo-format-buffer |
または，以下のようにします．
C-u C-c C-e C-b |
こうしたとき，Texinfoはファイルを分割せず，そのタグ表を生成しません．
分割されていないInfoファイルを作成後，そのためのタグ表を作成する必要があ ります．タグ付けしたいInfoファイルに移動し，以下を入力してください．
M-x Info-tagify |
(Info-tagifyの大文字の`I'に注意してください．)これで，有効化
が可能なタグ表を持つInfoファイルを作成します．
第三段階はInfoファイルを確認することです．
M-x Info-validate |
(Info-validateの大文字の`I'に注意してください．)簡単にいうと，
ステップは以下のようになります．
C-u M-x texinfo-format-buffer M-x Info-tagify M-x Info-validate |
ノード構造を有効にした後，通常の方法でtexinfo-format-bufferを再実
行し，そしてそれでタグ表を構築しファイルを自動的に分割する，または手動で
タグ表と分割されたファイルを作成することができます．
大きなファイルを分割したり，texinfo-format-bufferや
makeinfo-bufferコマンドで自動的にそれを行ったりすべきです．(一般
的に，書式化コマンドの一つでこの仕事を行います．See section 20.1 Infoファイルの作成.)
分割されたファイルは，間接的なサブファイルと呼ばれています．
Infoファイルはメモリを節約するため分割されます．小さなファイルでは， Emacsは情報を保つため大きなバッファを作成しません．
Infoファイルが30ノード以上ある場合，そのためにタグ表も作成すべきです．タ
グ表作成の詳細は，See section F.5.1 Info-validateの実行. (また，通常タグ表は，書式
化コマンドで自動的に作成されます．手動で作業をした場合のみ，タグ表を作成
する必要があります．ほとんどの場合，Info-validateで作業した大きな
分割されていないファイルでこれを行います．)
タグ付けと分割を行いたいファイルに移動し，二つのコマンドを入力してくださ い．
M-x Info-tagify M-x Info-split |
(`Info'の`I'が大文字であることに注意してください．)
Info-splitコマンドを使用するとき，バッファは間接的なサブファイル
を列挙する(小さな)Infoファイルに編集されます．このファイルは，移動した元
ファイルに保存されます．間接的なサブファイルは，元ファイルと同じディレク
トリに書き込まれ，元ファイル名に`-'と数字が追加されたファイル名にな
ります．
プライマリファイルはInfoファイルとして機能しますが，それはタグ表とサブファ イルのディレクトリだけを含みます．
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |