다음은 Texinfo 문서를 쓰는 몇가지 팁이다:
많은 색인 항목을 여러가지 방법으로 쓰라. 독자는 색인을 좋아한다; 색인은 많은 도움이 되고 편리하다.
글의 본체를 쓸때 색인 항목을 쓰는 것이 가장 쉽지만, 어떤 사람들은 나중에 색인을 쓰는 것을 더 좋아한다. 어떤 경우이든, 색인 항목은 그 항목이 적용되는 문단 앞에 쓴다. 일ㅓㅎ게 하면 여러 쪽으로 나눠진 문단의 첫번째 쪽으로 색인이 가리키게 된다.
다음에 가치있다고 생각하는 힌트들이 더 있다:
@section The Dog and the Fox @cindex Jumping, in general @cindex Leaping @cindex Dog, lazy, jumped over @cindex Lazy dog jumped over @cindex Fox, jumps over dog @cindex Quick fox jumps over dog The quick brown fox jumps over the lazy dog.(위의 예에서 다른 방법으로 쓰여진 같은 용어에 대한 항목을 보여준다는 것에 주목하라---`Lazy dog', `Dog, lazy'---이러면 독자는 이 용어를 다른 방법으로 찾을 수 있다.)
@table 명령 앞과 @end table 명령 뒤에는 빈칸을
넣는다; 하지만 @table 명령 뒤나 @end table 명령 앞에는
절대로 빈줄을 넣지 않는다.
예를 들어,
Types of fox: @table @samp @item Quick Jump over lazy dogs. @item Brown Also jump over lazy dogs. @end table @noindent On the other hand, ...같은 식으로
@itemize ... @end itemize와
@enumerate ... @end enumerate의 앞과 뒤에는 빈줄을
넣는다.
완전한 문장을 쓰는 것이 ...보다 더 읽기 좋다.
모든 매뉴얼에서 판과 버전 번호와 날짜를 세군데에 쓴다:
@ifinfo 부분. Texinfo 파일을 읽는 사람을 위한 부분이다.
@titlepage 부분. 인쇄된 매뉴얼을 읽는 사람을 위한 부분이다.
또, 첫번째 @ifinfo 부분 앞에 위에 대한 설명을 넣는 것도 좋다.
예를 들어:
@c ===> NOTE! <==
@c Specify the edition and version numbers and date
@c in *three* places:
@c 1. First ifinfo section 2. title page 3. top node
@c To find the locations, search for !!set
@ifinfo
@c !!set edition, date, version
This is Edition 4.03, January 1992,
of the @cite{GDB Manual} for GDB Version 4.3.
...
---또는 @set과 @value를 사용한다 (see section @value Example).
정의 명령은 @deffn, @defun, @defmac과 같은
것이다. 그리고 이 명령들은 통일된 형식으로 설명을 쓸 수 있도록 해 준다.
@table ...
@end table를 사용한다. @deffn이나 그 외의 정의 명령을
사용하지 않는다.
@TeX{} 명령으로 쓴다. 대문자로 된 `T'와
`X'에 유의하자. 이 명령은 포매팅 프로그램이 TeX을 만든 Donald
Knuth가 바라는 대로 이 고유명사를 타입셋하도록 한다.
Texinfo 파일을 포매팅하는 데 @example ... @end
example의 사이나 이와 비슷한 명령을 경우를 제외하고는 공백 문자를
사용하지 말라.
예를 들어, TeX은 다음을 fill한다.
@kbd{C-x v}
@kbd{M-x vc-next-action}
Perform the next logical operation
on the version-controlled file
corresponding to the current buffer.
그러므로 다음과 같이 보인다:
C-x v M-x vc-next-action Perform the next logical operation on the version-controlled file corresponding to the current buffer.
이 경우에, 위의 글은 @table, @item, 그리고
@itemx를 써서 표를 만들어야 한다.
@code를 사용한다. 예를
들어,
The main function is @code{vc-next-action}, ...
@var를 쓴다. 주위에 각괄호(angle bracket)을
쓰지 않는다.
인용문의 바깥에 점이나 그 외의 구두점을 찍어라: 만약 그 구두점이 인용문의 일부가 아니라면. 이런 관습은 미국내의 관습과는 상반되는 것이지만, 이렇게 하면 독자가 인용문의 내용과 전체 흐름을 구별할 수 있다.
예를 들어, 다음 문장은 점을 인용문이 끝난 뒤에 찍는다:
Evidently, `au' is an abbreviation for ``author''.
`au'는 `author.'(단어 뒤에 점이 온다)에 대한 약자가 아니기 때문이다.
The major function assists you in checking in a file to your version control system and registering successive sets of changes to it as deltas.
@dfn 명령을 소개되는 단어 주위에 써서, 독자가 그 의미를 아직
알고 있지 않다고 생각하는 것을 알린다. 그래서 설명을 계속해 나가면서 그
의미를 알아 갈 수 있도록 한다.
절대로 @pxref를 원래 사용되도록 만들어진 특별한 문맥 이외에는
사용하지 않는다: 그것은 괄호 안이고, 중괄호를 닫은 바로 다음에 괄호도
닫아야 한다. 어떤 포매팅 프로그램은 자동으로 구두점을 찍고, 어떤 것은
그렇지 않다. 이것은 이 명령이 괄호 안에 쓰였을 때만 인쇄물이나 Info
파일이나 출력이 제대로 보인다는 뜻이다.
셸에서 Emacs, GCC, 그리고 gawk와 같은 프로그램을 실행할 수 있다.
각 프로그램의 문서에는 여기에 대해 설명하는 절이 있어야 한다. 만약
이러한 절들의 노드 이름과 제목이 모두 다르다면, 독자는 이런 절을 찾는 데
어려움을 겪을 것이다.
이런 절의 이름은 `Invoking ...' 단어로 시작하는 구로 이름짓는다; 이렇게 하면 사용자는 이 절을 쉽게 찾을 수 있을 것이다.
C 함수를 콜(call)하는 법에 관해 설명할 때 @example을 사용한다면,
다음과 같이 ANSI C의 문법을 쓴다:
void dld_init (char *@var{path});
그리고 그 뒤에 나오는 설명에서, 인자의 값은 인자의 이름을 역시
@var로 하이라이트해서 참조한다.
다음과 같이 더이상 쓰지 않는 스타일은 피하라:
#include <dld.h> dld_init (path) char *path;
또, 단지 함수가 이 헤더 파일에 정의되었다는 것을 알리기 위해
#include를 declaration 위에 쓰는 것은 좋지 않다. 이렇게 하면
#include가 함수의 declaration과 가까운 곳에 들어 있는 것으로
오해를 일으킬 수 있다. 분명히 어떤 헤더 파일에 declaration이 들어
있다고 말하거나, 더 좋은 것은 함수들을 설명하는 절이 시작할 때 이 그룹의
함수들이 들어 있는 헤더 파일의 이름을 알리는 것이다.
다음은 피해야 하는 나쁘게 쓴 예이다:
다음 예에서, " ... you must @dfn{check in} the new
version."이라고 하는 편이 더 좋다.
When you are done editing the file, you must perform a
@dfn{check in}.
다음 예에서는, "... makes a unified interface such as VC mode possible."이라고 한다.
SCCS, RCS and other version-control systems all perform similar functions in broadly similar ways (it is this resemblance which makes a unified control mode like this possible).
그리고, 다음 예에서, `it'이 가리키는 것이 무엇인지 밝혀야 한다:
If you are working with other people, it assists in coordinating everyone's changes so they do not step on each other.
@bye 뒤에 자신을 위한 글을 써라. 어떤
포매팅 프로그램도 @bye 뒤에 오는 글을 포매팅하지 않는다; 마치
@ignore ... @end ignore 사이에 있는 것과 같다.
Go to the first, previous, next, last section, table of contents.