[ < ] | [ > ] | [ << ] | [ 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 by Autobuild on June 15, 2016 using texi2html 1.82.