[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
다음은 Texinfo 문서를 쓰는 몇가지 팁이다:
많은 색인 항목을 여러가지 방법으로 쓰라. 독자는 색인을 좋아한다; 색인은 많은 도움이 되고 편리하다.
글의 본체를 쓸때 색인 항목을 쓰는 것이 가장 쉽지만, 어떤 사람들은 나중에 색인을 쓰는 것을 더 좋아한다. 어떤 경우이든, 색인 항목은 그 항목이 적용되는 문단 앞에 쓴다. 일ㅓㅎ게 하면 여러 쪽으로 나눠진 문단의 첫번째 쪽으로 색인이 가리키게 된다.
다음에 가치있다고 생각하는 힌트들이 더 있다:
다음 예에서, 빈 줄이 “Leaping”이라는 색인 항목 뒤에 온다:
@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.
그러므로 다음과 같이 보인다:
이 경우에, 위의 글은 @table
, @item
, 그리고
@itemx
를 써서 표를 만들어야 한다.
@code
를 사용한다. 예를
들어,
The main function is @code{vc-next-action}, …
@var
를 쓴다. 주위에 각괄호(angle bracket)을
쓰지 않는다.
인용문의 바깥에 점이나 그 외의 구두점을 찍어라: 만약 그 구두점이 인용문의 일부가 아니라면. 이런 관습은 미국내의 관습과는 상반되는 것이지만, 이렇게 하면 독자가 인용문의 내용과 전체 흐름을 구별할 수 있다.
예를 들어, 다음 문장은 점을 인용문이 끝난 뒤에 찍는다:
Evidently, ‘au’ is an abbreviation for ``author''.
‘au’는 ‘author.’(단어 뒤에 점이 온다)에 대한 약자가 아니기 때문이다.
예를 들어, 다음 “check in”, “register” 그리고 “delta”는 첫번째로 나타나는 용어이다; 예제의 문장은 이해하기 좋도록 다시 쓰여야 한다.
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
사이에 있는 것과 같다.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on April 12, 2025 using texi2html 5.0.