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

B. Tips and Hints

다음은 Texinfo 문서를 쓰는 몇가지 팁이다:

Index, Index, Index!

많은 색인 항목을 여러가지 방법으로 쓰라. 독자는 색인을 좋아한다; 색인은 많은 도움이 되고 편리하다.

글의 본체를 쓸때 색인 항목을 쓰는 것이 가장 쉽지만, 어떤 사람들은 나중에 색인을 쓰는 것을 더 좋아한다. 어떤 경우이든, 색인 항목은 그 항목이 적용되는 문단 앞에 쓴다. 일ㅓㅎ게 하면 여러 쪽으로 나눠진 문단의 첫번째 쪽으로 색인이 가리키게 된다.

다음에 가치있다고 생각하는 힌트들이 더 있다:

Blank Lines

Complete Phrases

완전한 문장을 쓰는 것이 …보다 더 읽기 좋다.

Editions, Dates and Versions

모든 매뉴얼에서 판과 버전 번호와 날짜를 세군데에 쓴다:

  1. 첫번째 @ifinfo 부분. Texinfo 파일을 읽는 사람을 위한 부분이다.
  2. @titlepage 부분. 인쇄된 매뉴얼을 읽는 사람을 위한 부분이다.
  3. ‘Top’ 노드. Info 파일을 읽는 사람을 위한 부분이다.

또, 첫번째 @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).

Definition Commands

정의 명령은 @deffn, @defun, @defmac과 같은 것이다. 그리고 이 명령들은 통일된 형식으로 설명을 쓸 수 있도록 해 준다.

Capitalization

Spaces

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, @samp, @var, and ‘---

Periods Outside of Quotes

인용문의 바깥에 점이나 그 외의 구두점을 찍어라: 만약 그 구두점이 인용문의 일부가 아니라면. 이런 관습은 미국내의 관습과는 상반되는 것이지만, 이렇게 하면 독자가 인용문의 내용과 전체 흐름을 구별할 수 있다.

예를 들어, 다음 문장은 점을 인용문이 끝난 뒤에 찍는다:

 
Evidently, ‘au’ is an abbreviation for ``author''.

au’는 ‘author.’(단어 뒤에 점이 온다)에 대한 약자가 아니기 때문이다.

Introducing New Terms

@pxref

절대로 @pxref를 원래 사용되도록 만들어진 특별한 문맥 이외에는 사용하지 않는다: 그것은 괄호 안이고, 중괄호를 닫은 바로 다음에 괄호도 닫아야 한다. 어떤 포매팅 프로그램은 자동으로 구두점을 찍고, 어떤 것은 그렇지 않다. 이것은 이 명령이 괄호 안에 쓰였을 때만 인쇄물이나 Info 파일이나 출력이 제대로 보인다는 뜻이다.

Invoking from a Shell

셸에서 Emacs, GCC, 그리고 gawk와 같은 프로그램을 실행할 수 있다. 각 프로그램의 문서에는 여기에 대해 설명하는 절이 있어야 한다. 만약 이러한 절들의 노드 이름과 제목이 모두 다르다면, 독자는 이런 절을 찾는 데 어려움을 겪을 것이다.

이런 절의 이름은 ‘Invoking …’ 단어로 시작하는 구로 이름짓는다; 이렇게 하면 사용자는 이 절을 쉽게 찾을 수 있을 것이다.

ANSI C Syntax

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이 들어 있다고 말하거나, 더 좋은 것은 함수들을 설명하는 절이 시작할 때 이 그룹의 함수들이 들어 있는 헤더 파일의 이름을 알리는 것이다.

Bad Examples

다음은 피해야 하는 나쁘게 쓴 예이다:

다음 예에서, “ … 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.

And Finally …


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

This document was generated by Autobuild on September 28, 2013 using texi2html 1.82.