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

G. Formatting Mistakes

문서 내용의 실 수 이외에, 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-regionmakeinfo-buffer를 사용해서) 파일을 포매팅하고 그 외의 애러를 찾아내라. 이것이 Teixnfo와 함께 작업하는 가장 좋은 방법이다. 하지만, makeinfo를 사용하지 못하거나, 문제가 매우 해결하기 어렵다면, 이 부록에 설명된 도구들을 사용하면 된다.


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

G.1 Catching Errors with Info Formatting

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에서 이 노드를 읽다가 f<RET>을(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’에서 다시 돌아올 수 있다.)


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

G.2 Catching Errors with TeX Formatting

또, 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은 언제나 도움을 주지는 못한다. 그리고 때로 어디가 잘못되었는지 찾으려면 셜록홈즈와 같아야 한다.

어떤 경우ㄷㄴ, 이와 같은 문제를 만나면, 다음 세가지중 하나를 할 수 있다.

  1. ?’ 프롬프트에 대해 <RET>를 눌러 TeX이 실행을 계속하고, 이 애러를 무시하도록 한다.
  2. ?’ 프롬프트에 대해 r <RET>을 눌러 가능한한 모든 애러를 무시하고 실행을 계속하도록 한다.

    어떤 경우에는 이것이 최선이다. 하지만, 조심하기 바란다: 한개의 애러는 그 결과가 파일의 나머지 부분에게까지 영향을 미쳐 계속해서 애러 메세지를 만들어 내는 수도 있다. TeX에서 그런 애러 메세지의 사태가 나지 않도록 하려면, C-c를 누른다. (혹은 Emacs내에서 셸을 실행한다면 C-c C-c을 누른다.)

  3. ?’ 프롬프트에 대해 x <RET>을 눌러 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과 작업하는 것이다.)


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

G.3 Using 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.texi’ 파일의 4337, 4393, 4417번째 줄이 각각 @section, @subheading, 그리고 @subsection으로 시작한다는 것을 뜻한다. 만약 커서를 ‘*Occur*’ 윈도우에 옮기면, 커서를 이 줄들 중 하나에 올려 놓은 다음 C-c C-c 명령을 실행하여 (occur-mode-goto-occurrence), 이 Texinfo 파일의 해당되는 지점으로 이동할 수 있다. occur-mode-goto-occurrence에 대한 더 많은 정보는 See (emacs)Other Repeating Search section ‘Using Occur’ in The GNU Emacs Manual.

*Occur*’ 윈도우의 첫번째 줄은 texinfo-heading-pattern으로 지정하는 regular expression이 적혀 있다. 이 regular expression은 texinfo-show-structure가 찾는 패턴이다. 더 자세한 정보는 See (emacs)Regexps section ‘Using Regular Expressions’ in The GNU Emacs Manual.

texinfo-show-structure 명령을 실행할 때, Emacs는 전체 버퍼의 구조를 표시할 것이다. 만약 버퍼의 일부의 구조만을 보고 싶다면, 예를 들어 한개 장의 구조만을 보고 싶다면 C-x n n (narrow-to-region) 명령으로 리전을 표시한다. (See (emacs)Narrowing 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 파일의 구조를 상기할 수 있다; 그리고 잘못 이름붙인 노드가 있거나 절을 빼먹었다면, 이 리스트를 보고 그 잘못을 고칠 수 있다.


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

G.3.1 Tagifying a File

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.


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

G.4 Using 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 (emacs)Regexps 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 (emacs)Other Repeating Search section ‘Using Occur’ in The GNU Emacs Manual, for more information.


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

G.5 Finding Badly Referenced Nodes

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.


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

G.5.1 Running 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.


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

G.5.2 Creating an 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.


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

G.5.3 Splitting a File Manually

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.


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

This document was generated by Autobuild on July 8, 2017 using texi2html 1.82.