Go to the first, previous, next, last section, table of contents.

Nodes

node는 Texinfo 파일의 주요한 조각조각이다. node 자신은 어떤 계층적인 혹은 파일의 구조에 관한 정보가 없다. node는 다른 node의 이름인 node pointer를 내부에 가질수 있고, node를 열거한 menu를 가질 수도 있다. Info에서, 이동명령은 pointer가 가리키는 node나 menu에 열거된 node로 이동시킨다. chapter, section, subsection 등이 인쇄된 책에서 구조를 제공하듯이 node pointer와 menu는 Info 파일에 구조를 제공해 준다.

node와 메뉴명령과 chapter structuring 명령은 서로 독립적이다;

Info 파일을 구조화하는 node pointer와 menu는 어떤 방법으로든 하고싶은 대로 사용할 수 있다; 그리고 Info 출력이 인쇄된 출력과 다른 구조를 갖도록 Texinfo 파일을 쓸 수도 있다. 하지만, 대부분의 Texinfo 파일은 Info 출력의 구조가 인쇄된 출력의 구조와 갖도록 쓰여 있다. 그렇지 않게 하면 불편하다.

Node and Menu Illustration

여기 있는 것은 앞에서 각각 2개씩의 section이 있는 세개의 chapter가 있는 Texinfo 파일을 보여주는 그림이다.

"root"는 diagram의 맨 위에 있고, "leaves"는 바닥에 있다는 것에 유의하라. 이것이 diagram을 그리는 전통적인 방법이다; 이 방법은 뒤집어진 나무를 그린다. 이러한 이유로, root node는 `Top' node라고 부르고, `Up' node pointer는 root에 더 가까이 가게 해 준다. 

                          Top
                           |
         -------------------------------------
        |                  |                  |
     Chapter 1          Chapter 2          Chapter 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
 Section  Section   Section  Section   Section  Section
   1.1      1.2       2.1      2.2       3.1      3.2

Chapter 2의 node의 시작은 다음과 같이 쓴다; 

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

이 @node 줄은 이 node의 이름이 "Chapter 2"이고, `다음'(`Next') node의 이름이 "Chapter 3'이고, `이전'(`Previous') node의 이름이 "Chapter 1"이고, `윗'(`Up') node의 이름이 "Top"이라는 것을 지정한다.

주의: `Next'는 매뉴얼의 같은 계층적인 단계의 다음 node를 가리키고, Texinfo 파일의 다음 node를 가리킬 필요가 없다. Texinfo 파일에서, 다음 node는 더 낮은 단계에 있을 수도 있다--section 단계의 node가 chapter 단계의 node다음에 올수도 있고, subsection 단계의 node가 section 단계의 node 다음에 올 수도 있다. `Next'와 `Previous'는 같은 계층적인 단계의 node를 가리킨다. (`Top' node에서는 이 규칙의 예외가 있다. `Top' node는 그 단계에 하나밖에 없기 때문에, `Next'는 첫번째로 다음에 나오는 (대부분 chapter이거나 chapter 단계인) node를 가리킨다.

Info를 사용해서 Section 2.1과 2.2로 가려면, Chapter 2 안에 menu가 필요하다. 다음과 같이 Section 2.1이 시작하기 전에 menu를 쓴다; 

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

Section 2.1의 node를 다음과 같이 쓴다; 

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

Info 형식에서, node의 `Next'와 `Previous' pointer는 보통 같은 단계에 있는 다른 node들을 가리킨다---chapter에서 chapter 혹은 section에서 section이다 (가끔, `Previous' pointer는 위를 가리킨다); `up' pointer는 보통 한단계 위의 (`Top' node에 더 가까운) node를 가리킨다; 그리고 `Menu'는 한단계 아래의 (`leaves'에 더 가까운) node들을 가리킨다. (상호 참조는 어떤 단계의 node라도 가리킬 수 있다; section Cross References 참조.)

보통, @node 명령과 chapter 구조 명령은 연속해서 사용되고, indexing 명령들이 따라 나온다. (@node 줄 다음에 어느 pointer가 어느 것인지 상기할 수 있는 주석 줄을 넣을 수도 있다.)

다음은 이 매뉴얼의 "Ending a Texinfo File"이라는 chapter의 시작 부분이다. 여기에서 @node줄 다음에 주석 줄이 나오고, @chapter 줄이 나오고, 그 다음에 indexing 줄이 나온다. 

@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

The @node Command

node는 @node 명령으로 시작하는 글의 조각이고, 다음 @node 명령이 올 때까지 계속된다. node의 정의는 chapter나 section과는 다르다. chapter 안에 section이 들어갈 수 있고, section 안에 subsection이 들어갈 수 있다; 하지만 node는 subnode가 안에 들어갈 수 없다; node의 글은 다음번 @node 명령이 파일에 나타날 때까지 계속될 뿐이다. 한개의 node는 보통 한개의 chapter 구조 명령을 갖고 있고, 그것은 @node 줄 다음에 나온다. 한편, 인쇄된 매뉴얼에서 node는 상호 참조를 위해 쓰여서, chapter나 section은 몇개의 node라도 안에 포함할 수 있다. 사실, chapter는 보통 각 section, subsection, 그리고 subsubsection에 해당하는 여러개의 node를 포함한다.

node를 만드렴ㄴ, @node 명령을 줄이 시작할 때 쓰고, 같은 줄의 나머지에 계속해서 4개의 인수를 쉼표로 구분해서 쓴다. 이 인수들은 순서대로 node의 이름, `Next', `Previous', 그리고 `Up' pointer의 이름이다. 각 pointer앞에 공백문자를 사이에 넣을 수도 있다; 공백문자는 무시된다. node의 이름, `Next', `Previous', 그리고 `Up' pointer의 이름들 모두를 같은 줄에 써양 한다. 그렇지 않으면 formatter가 실패할 것이다. (Info의 node에 관한 더 자세한 정보는 See Info file `info', node `Top' 참조)

보통, @node 줄 다음에 바로 chapter 구조 명령 줄을 쓴다---예를 들어, @section이나 @subsection 줄과 같은 것이다. (See section Types of Structuring Command.)

주의: GNU Emacs Texinfo mode의 updating 명령은 @node 줄 다음에 chapter 구조 줄이 나올 때만 동작한다. See section Updating Requirements.

TeX은 @node 줄을 상호 참조에 사용할 이름을 알아보기 위해 사용한다. 이러한 이유로, 인쇄하기 위해서 format하려고 하는 Texinfo 파일은 Info로 format하려고 하지 않더라도 @node 줄을 반드시 써야 한다. (이 문장의 마지막에 있는 것과 같은 상호 참조는 @xref와 그와 관련된 명령들로 만들 수 있다; section Cross References 참조.)

node의 이름은 node를 구분해 준다. pointer는 다른 node로 갈 수 있게 해 주고, 그 node의 이름으로 만들어 진다.

보통, node의 `Up' pointer는 menu에서 그 node를 언급한 node의 이름이 쓰여 있다. node의 `Next' pointer는 그 menu에서 다음에 나오는 node의 이름으로 만들어지고, node의 `Previous' pointer는 그 menu에서 앞에 나오는 node의 이름으로 만들어 진다. node의 `Previous' node가 `Up' node와 같을 때, 두개의 node pointer는 같은 node의 이름으로 만들어 진다.

보통, Texinfo 파일의 첫번째 node는 `Top' node이고, 그 `Up'과 `previous' pointer는 `dir' 파일을 가리킨다. `dir' 파일은 모든 Info가 있는 main menu가 들어 있다.

`Top' node 자신은 그 manual의 main 혹은 master menu가 들어 있다. 또, `Top' node에 그 매뉴얼의 간단한 설명을 담는 것이 좋다. Texinfo 파이리의 첫번째 node를 쓰는 방법에 대해서는 See section The First Node.

How to Write an @node Line

@node 줄을 가장 쉽게 쓰는 방법은 다음과 같이 @node를 줄이 시작할 때 쓰고, 그 다음에 그 node의 이름을 적는 것이다. 

@node node-name

GNU Emacs를 사용한다면, Texinfo mode의 update node 명령을 사용해서 pointer의 이름을 넣을 수 있다; 또는 Texinfo 파일에서 pointer를 빼 놓고, makeinfo가 Info 파일에 pointer를 넣도록 할 수도 있다. (See section Using Texinfo Mode, 그리고 section Creating Pointers with makeinfo.)

그렇지 않으면, 직접 `Next', `Previous', 그리고 `Up' pointer를 넣을 수도 있다. 이렇게 하려면 Texinfo mode의 keyboard 명령 C-c C-c n이 유용하다. 이 명령은 `@node'와 올바른 순서로 pointer의 이름들을 열거한 주석 줄을 넣는다. 이 주석 줄은 어떤 argument가 어떤 pointer인지 알수 있게 도와준다. 이 주석 줄은 특히 Texinfo에 익숙하지 못할 때 유용하다.

`Next', `Previous', 그리고 `Up' pointer가 있는 node 줄에 대한 틀은 다음과 같다: 

@node node-name, next, previous, up

원한다면, 첫번째 글을 쓸때 @node 라인을 하나도 쓰지 않고, Texinfo-insert-node-lines 명령을 써서 @node줄들을 한꺼번에 만들 수도 있다. 하지만, 이 방법은 권장하지 않는다. 그 부분을 쓰는 동시에 node의 이름을 지어서 쉽게 상호 참조를 만들수 있는 편이 더 좋다. 상호 참조가 많은 것은 좋은 Info 파일의 중요한 특징의 하나이다.

@node 줄을 넣은 후에, 바로 다음에 chapter 혹은 section에 대한 @-명령과 그 이름을 써야 한다. 그 다음에 (이것은 아주 중요하다!), 색인 항목을 쓴다. 보통, 색인에서 같은 node를 참조할 때, 최소한 두개 혹은 너덧가지 정도까지 많은 방법이 있다. 모두 사용하라. 이렇게 하면 사람들이 그 node를 찾기 훨씬 더 쉬울 것이다.

@node Line Tips

세가지의 권장사항이 있다:

@node Line Requirements

다음은 @node 줄에 필요한 사항들이다:

The First Node

Texinfo 파일의 첫번째 node는 포함되는 파일을 제외하고 (see section Include Files) `Top' node이다.

`Top' node(`top'이나 `Top'이라는 이름이 되어야 한다)는 그 `Up'과 `Previous' node의 이름으로 또 다른 파일의 node를 갖고 있어야 하고, 이 파일로 인도하는 menu가 있는 node이다. 파일 이름은 괄호 안에 지정한다. 만약 그 파일이 Info directory 파일에 직접 설치되어 있다면, `Top' node의 부모로 `(dir)'를 쓴다; 이것은 `(dir)top'을 짧게 쓴 것이고, Info의 주 메뉴가 있는 `dir' 파일 안에 있는 `Top' node를 지정한다. 예를 들어, 이 매뉴얼의 @node Top 줄은 다음과 같다: 

@node Top, Overview, (dir), (dir)

(Texinfo updating 명령이나 makeinfo 유틸리티를 써서 이 `Next'와 `(dir)' pointer를 자동으로 넣을 수 있다.)

Info 파일을 `info' directory에 설치하는 것에 대한 자세한 설명은 See section Installing an Info File.

`Top' node는 그 문서의 주 menU가 들어 있다.

The @top Sectioning Command

특별한 sectioning 명령인 @top은 @node Top 줄고 함께 쓰이도록 만들어 져 있다. @top sectioning 명령은 makeinfo가 파일의 `Top' node를 표시하도록 한다. 이것은 makeinfo가 node pointer를 자동으로 넣기 위해 필요한 정보를 제공해 준다. @top 명령을 줄이 시작할 때 쓰고 바로 @node Top 줄을 쓴다.

Info에서, @top sectioning 명령은 제목이 asterisk로 된 밑주로가 함께 한 줄에 나타나도록 한다.

TeX과 texinfo-format-buffer에서, @top sectioning 명령은 @unnumbered와 동의어일 뿐이다. 이 formatter중 어떤 것도 @top 명령이 필요없고, 특별한 것도 없다. 이 formatter를 쓸 때 @node Top 줄 다음에 @chapter나 unnumbered를 써도 된다. 또, pointer나 menu를 update하려고, Texinfo updating 명령을 쓸 때, @chapter나 @unnumbered를 써도 된다.

The `Top' Node Summary

`Top' node에서 @top 줄 다음에 main 혹은 master menu 앞에 간단한 요약을 써서 독자에게 도움을 줄 수 있다. 요약은 간단하게 그 문서에 대해 설명해야 한다. Info에서, 이 요약은 master menu 바로 앞에 나와야 한다. 인쇄된 매뉴얼에서 이 요약은 한 페이지에 단독으로 나올 것이다.

인쇄된 매뉴얼에서 요약이 나오지 않게 하려면, @node Top줄과 @top sectioning 명령 줄과 그 외 sectioning 명령줄을 포함해서 전체 `Top' node를 @ifinfo와 @end ifinfo로 둘러싸면 된다. 이렇게 하면, 어떤 글도 인쇄된 매뉴얼에 나타나지 못한다. (see section Conditionally Visible Text). 인쇄된 매뉴얼을 읽는 사람을 위해서 첫번째 장이 시작할 때 @iftex ... @end iftex 사이에 `Top' node에 있는 간략한 설명을 반복해서 적을 수 있다. 이렇게 하는 것이 종이를 아끼고, 더 간결하게 보인다.

요약에 이 매뉴얼이 적용되는 프로그램의 버전 번호를 적어야 한다. 이렇게 하면 독자가 어떤 매뉴얼이 프로그램의 어떤 버전에 해당되는지 알 수 있다. 매뉴얼이 프로그램보다도 더 자주 바뀌거나, 프로그램과는 독립적으로 바뀐다면, 그 매뉴얼의 판번호도 포함해야 한다. (표지도 이 정보를 포함해야 한다; section @titlepage.)

Creating Pointers with makeinfo

makeinfo 프로그램은 node pointer가 없는 계층적으로 조직된 파일에서 node pointer를 자동으로 만드는 기능이 있다.

이 기능을 사용할 때, node의 이름 다음에 `Next', `Previous', 그리고 `Up' pointer를 쓸 필요가 없다. 하지만, @chapter나 @section같은 sectioning 명령을 pointer가 생략된 각 @node 줄 바로 다음에 써야 한다. node 줄 다음에 주석 줄을 쓸 수 없다; section 줄은 반드시 직후에 나와야 한다.

또, `Top' @node줄 다음에 @top으로 시작하는 줄을 써서 파일의 `Top' node를 표시해야 한다. See section @top.

마지막으로, node의 계층적으로 한단계나 더 위의 menu에 (`Top' node를 제외하고) 각 node의 이름을 써야 한다.

makeinfo의 이러한 node pointer 삽입 기능은 Texinfo mode의 pointer 생성과 update 명령의 대안이다. (See section Updating Nodes and Menus.) 이 기능은 Texinfo 문서를 쓰는데 GNU Emacs를 쓰지 않는 사람에게 특히 유용하다.

Go to the first, previous, next, last section, table of contents.