문서 내용의 실 수 이외에, Texinfo에서 할 수 있는 두가지 종류의 실수가 있다: @-명령을 쓸 때 실수한 경우와, 노드와 장의 구조에서 실수한 경우이다.
emacs에는 @-명령어의 실수를 위한 두가지 도구와 구조상의 실수를 고치기 위한 두가지 도구가 있다.
@-명령의 문제를 찾을 때, 문제가 일어난 리전(region)에 대해서 TeX이나 리전(region) 포매팅 명령을 실행한다; 실제로는, 이런 명령을 각 리전(region)을 쓸 때마다 각 리전(region)에 대해 실행할 수 있다.
노드나 장의 구조의 문제를 찾을 때, C-c C-s
(texinfo-show-structure)와 이와 관련된 occur 명령을 쓸 수
있고, M-x Info-validate 명령을 쓸 수 있다.
makeinfo 프로그램은 애러를 찾아내고 알려주는 일을 매우 잘해
낸다---texinfo-format-region이나 texinfo-format-buffer
보다 더 잘한다. 또, 자동으로 노드 포인터와 메뉴를 만들고 업데이트하는
여러가지 기능들은 인간이 저지를 수 있는 많은 잘못을 없애준다.
할 수만 있다면, 포인터와 메뉴를 만드는데 업데이트 명령을 쓰기 바란다.
이 명령들은 많은 애러를 막아준다. 그리고 makeinfo를 사용해서
(또는 이 명령을 Texinfo 모드에서 사용하는 명령인
makeinfo-region과 makeinfo-buffer를 사용해서) 파일을
포매팅하고 그 외의 애러를 찾아내라. 이것이 Teixnfo와 함께 작업하는 가장
좋은 방법이다. 하지만, makeinfo를 사용하지 못하거나, 문제가 매우
해결하기 어렵다면, 이 부록에 설명된 도구들을 사용하면 된다.
Texinfo 파일의 일부를 쓴 후에, texinfo-format-region이나
makeinfo-region 명령으로 그 리전(region)이 제대로 포매팅되는지
확인할 수 있다.
하지만, 마찬가지로 어떤 이유이든 makeinfo-region 명령을 쓸 수
없어서 이 절을 읽고 있다면; 즉, 이 절의 나머지는
texinfo-format-region을 쓴다고 가정한다.
@-명령에 실수를 했다면, texinfo-format-region은 애러 바로 다음
위치에서 처리를 멈추고 애러메세지를 출력할 것이다. 버퍼의 어디에 애러가
있는지 보려면, `*Info Regino*'버퍼로 이동한다; 커서는 애러 위치
바로 다음 지점에 놓이게 될 것이다. 또, 애러가 발생한 장소 (정확히
말해서, 애러를 찾은 장소)이후는 포매팅되지 않을 것이다.
예를 들어, 우연히 @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에서 이 노드를 읽다가
fRET을(Info-follow-reference) 누른다면 다음과 같은
애러 메세지를 보게 될 것이다:
No such node: "Catching Mistakes) The only way ...
이 현상은 이와같은 애러가 있는 예를 이 노드의 첫번째 상호 참조로
이해하고, Info의 f명령을 타이프한 직후 RET을 누르면, Info는
참조된 노드로 가려고 시도할 것이다. 만약 f catch TAB
RET을 누르면, Info는 노드의 이름을 예에 쓰여 있는 것처럼 정확히
보충해서 `Catching Mistakes' 노드로 데려다 줄 것이다. (만약 이것을
시도하려고 한다면, l(Info-last)를 눌러 `Catching
Mistakes'에서 다시 돌아올 수 있다.)
또, TeX으로 파일을 포매팅할 때에도 실수를 찾아낼 수 있다.
보통, texinfo-format-buffer (또는, 더 좋은 방법으로
makeinfo-buffer)를 같은 파일에 실행시킨 후에 TeX의 문제를
해결할 것이다. 왜냐하면 때때로 texinfo-format-buffer는
TeX보다 더 적은 애러 메세지를 표시하기 때문이다. (See section Catching Errors with Info Formatting, for more information.)
예를 들어, TeX이 파일 일부가 다음과 같은 어떤 Texinfo 파일에 대해 실행되었다고 하자:
---------- 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 내부 명령어이다. `1.27'은 이 Texinfo의 27번째 줄에서 문제를 발견했다는 뜻이다. `?'는 이러한 상황에서 TeX이 사용하는 프롬프트이다.
불행히도, TeX은 언제나 도움을 주지는 못한다. 그리고 때로 어디가 잘못되었는지 찾으려면 셜록홈즈와 같아야 한다.
어떤 경우ㄷㄴ, 이와 같은 문제를 만나면, 다음 세가지중 하나를 할 수 있다.
Emacs에서 TeX을 실행하고 있다면 기억하기 바란다. 셸 버퍼에 들어 간 다음 TeX이 `?' 프롬프트를 표시하는 줄에 포인트를 위치해야 한다.
가끔 TeX은 문제가 있는데도 불구하고 애러 메세지를 내지 않고 파일을
포매팅하는 경우가 있다. 이런 경우는 보통 어떤 명령이 끝나지 않았는데
어쨌든 TeX이 처리를 계속 할 수 있는 경우에 일어난다. 예를 들어, 만약
번호 없는 리스트를 끝내는 @end itemize 명령을 쓰지 않았다면,
TeX은 DVI 파일을 쓸 것이고 그걸 인쇄할 수 있다. TeX이 표시할 수
있는 유일한 메세지는 다음과 같이 좀 신비스러운 코멘트이다:
(@end occurred inside a group at level 1)
하지만, DVI 파일을 인쇄할 수 있다면 번호 없는 리스트 이후의 파일이 전부
그 리스트의 일부분인 것처럼 들여 쓰기 되어 있다는 것응ㄹ 알아낼 것이다.
위의 애러 메세지는 @end 명령이 파일의 어딘가에 나타나기를
기대한다고 말하는 방법이다; 하지만, TeX은 어디에 이 명령이 필요한지는
알지 못한다.
가장 찾기 어렵기로 악명높은 또 한나의 애러는 @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-structureTexinfo 파일의 노드, 장, 절, 그리고 아래절들을 찾는 것은 쉬운 일만은 아니다. 특히 다른 사람이 쓴 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.texi' 파일의 4337, 4393, 4417번째 줄이 각각
@section, @subheading, 그리고 @subsection으로
시작한다는 것을 뜻한다. 만약 커서를 `*Occur*' 윈도우에 옮기면,
커서를 이 줄들 중 하나에 올려 놓은 다음 C-c C-c 명령을 실행하여
(occur-mode-goto-occurrence), 이 Texinfo 파일의 해당되는 지점으로
이동할 수 있다. occur-mode-goto-occurrence에 대한 더 많은 정보는
See section `Using Occur' in The GNU Emacs Manual.
`*Occur*' 윈도우의 첫번째 줄은 texinfo-heading-pattern으로
지정하는 regular expression이 적혀 있다. 이 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 파일의 구조를 상기할 수 있다; 그리고 잘못 이름붙인 노드가 있거나 절을 빼먹었다면, 이 리스트를 보고 그 잘못을 고칠 수 있다.
After creating an unsplit Info file, you must create a tag table for it. Visit the Info file you wish to tagify and type:
M-x Info-tagify
(Note the upper case `I' in Info-tagify.) This creates an
Info file with a tag table that you can validate.
The third step is to validate the Info file:
M-x Info-validate
(Note the upper case `I' in Info-validate.)
In brief, the steps are:
C-u M-x texinfo-format-buffer M-x Info-tagify M-x Info-validate
After you have validated the node structure, you can rerun
texinfo-format-buffer in the normal way so it will construct a
tag table and split the file automatically, or you can make the tag
table and split the file manually.
occur
Sometimes the texinfo-show-structure command produces too much
information. Perhaps you want to remind yourself of the overall structure
of a Texinfo file, and are overwhelmed by the detailed list produced by
texinfo-show-structure. In this case, you can use the occur
command directly. To do this, type
M-x occur
and then, when prompted, type a regexp, a regular expression for
the pattern you want to match. (See section `Regular Expressions' in The GNU Emacs Manual.) The occur command works from
the current location of the cursor in the buffer to the end of the
buffer. If you want to run occur on the whole buffer, place
the cursor at the beginning of the buffer.
For example, to see all the lines that contain the word `@chapter' in them, just type `@chapter'. This will produce a list of the chapters. It will also list all the sentences with `@chapter' in the middle of the line.
If you want to see only those lines that start with the word
`@chapter', type `^@chapter' when prompted by
occur. If you want to see all the lines that end with a word
or phrase, end the last word with a `$'; for example,
`catching mistakes$'. This can be helpful when you want to see
all the nodes that are part of the same chapter or section and
therefore have the same `Up' pointer.
See section `Using Occur' in The GNU Emacs Manual, for more information.
You can use the Info-validate command to check whether any of
the `Next', `Previous', `Up' or other node pointers fail to point to a
node. This command checks that every node pointer points to an
existing node. The Info-validate command works only on Info
files, not on Texinfo files.
The makeinfo program validates pointers automatically, so you
do not need to use the Info-validate command if you are using
makeinfo. You only may need to use Info-validate if you
are unable to run makeinfo and instead must create an Info file
using texinfo-format-region or texinfo-format-buffer, or
if you write an Info file from scratch.
Info-validate
To use Info-validate, visit the Info file you wish to check and
type:
M-x Info-validate
(Note that the Info-validate command requires an upper case
`I'. You may also need to create a tag table before running
Info-validate. See section Tagifying a File.)
If your file is valid, you will receive a message that says "File appears valid". However, if you have a pointer that does not point to a node, error messages will be displayed in a buffer called `*problems in info file*'.
For example, Info-validate was run on a test file that contained
only the first node of this manual. One of the messages said:
In node "Overview", invalid Next: Texinfo Mode
This meant that the node called `Overview' had a `Next' pointer that did not point to anything (which was true in this case, since the test file had only one node in it).
Now suppose we add a node named `Texinfo Mode' to our test case but we do not specify a `Previous' for this node. Then we will get the following error message:
In node "Texinfo Mode", should have Previous: Overview
This is because every `Next' pointer should be matched by a `Previous' (in the node where the `Next' points) which points back.
Info-validate also checks that all menu entries and cross references
point to actual nodes.
Note that Info-validate requires a tag table and does not work
with files that have been split. (The texinfo-format-buffer
command automatically splits large files.) In order to use
Info-validate on a large file, you must run
texinfo-format-buffer with an argument so that it does not split
the Info file; and you must create a tag table for the unsplit
file.
You can run Info-validate only on a single Info file that has a
tag table. The command will not work on the indirect subfiles that
are generated when a master file is split. If you have a large file
(longer than 70,000 bytes or so), you need to run the
texinfo-format-buffer or makeinfo-buffer command in such
a way that it does not create indirect subfiles. You will also need
to create a tag table for the Info file. After you have done this,
you can run Info-validate and look for badly referenced
nodes.
The first step is to create an unsplit Info file. To prevent
texinfo-format-buffer from splitting a Texinfo file into
smaller Info files, give a prefix to the M-x
texinfo-format-buffer command:
C-u M-x texinfo-format-buffer
or else
C-u C-c C-e C-b
When you do this, Texinfo will not split the file and will not create a tag table for it.
You should split a large file or else let the
texinfo-format-buffer or makeinfo-buffer command do it
for you automatically. (Generally you will let one of the formatting
commands do this job for you. See section Creating an Info File.)
The split-off files are called the indirect subfiles.
Info files are split to save memory. With smaller files, Emacs does not have make such a large buffer to hold the information.
If an Info file has more than 30 nodes, you should also make a tag
table for it. See section Running Info-validate, for information
about creating a tag table. (Again, tag tables are usually created
automatically by the formatting command; you only need to create a tag
table yourself if you are doing the job manually. Most likely, you
will do this for a large, unsplit file on which you have run
Info-validate.)
Visit the Info file you wish to tagify and split and type the two commands:
M-x Info-tagify M-x Info-split
(Note that the `I' in `Info' is upper case.)
When you use the Info-split command, the buffer is modified into a
(small) Info file which lists the indirect subfiles. This file should be
saved in place of the original visited file. The indirect subfiles are
written in the same directory the original file is in, with names generated
by appending `-' and a number to the original file name.
The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles.
Go to the first, previous, next, last section, table of contents.