Fresh Fish 4/FreshFish_May-June1994.bin/gnu/info/texi.info-9

GNU Info File | 1994-02-24 | 47KB | 925 lines

This is Info file texi.info, produced by Makeinfo-1.55 from the input
file texi.texi.
   This file documents Texinfo, a documentation system that uses a
single source file to produce both on-line information and a printed
manual.
   Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
   This is the second edition of the Texinfo documentation,
and is consistent with version 2 of `texinfo.tex'.
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.
File: texi.info,  Node: Tips,  Next: Sample Texinfo File,  Prev: Command List,  Up: Top
Tips and Hints
**************
   Here are some tips for writing Texinfo documentation:
   * Write in the present tense, not in the past or the future.
   * Write actively!  For example, write "We recommend that ..." rather
     than "It is recommended that ...".
   * Use 70 or 72 as your fill column.  Longer lines are hard to read.
   * Include a copyright notice and copying permissions.
Index, index, index!
....................
   Write many index entries, in different ways.  Readers like indices;
they are helpful and convenient.
   Although it is easiest to write index entries as you write the body
of the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.
   Here are more hints we have found valuable:
   * Write each index entry differently, so each entry refers to a
     different place in the document.  The index of an Info file lists
     only one location for each entry.
   * Write index entries only where a topic is discussed significantly.
     For example, it is not useful to index "debugging information" in
     a chapter on reporting bugs.  Someone who wants to know about
     debugging information will certainly not find it in that chapter.
   * Consistently capitalize the first word of every index entry, or
     else use lower case.  According to convention, you should
     capitalize the first word of an index entry.  However, this
     practice may make an index look crowded.  Some writers prefer
     lower case.  Regardless of which you prefer, choose one style and
     stick to it.  Mixing the two styles looks bad.
   * Always capitalize or use upper case for those words in an index for
     which this is proper, such as names of countries or acronyms.
   * Write the indexing commands that refer to a whole section
     immediately after the section command, and write the indexing
     commands that refer to the paragraph before the paragraph.
     In the example that follows, a blank line comes after the index
     entry for "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.
     (Note that the example shows entries for the same concept that are
     written in different ways--`Lazy dog', and `Dog, lazy'--so readers
     can look up the concept in different ways.)
Blank lines
...........
   * Insert a blank line between a sectioning command and the first
     following sentence or paragraph, or between the indexing commands
     associated with the sectioning command and the first following
     sentence or paragraph, as shown in the tip on indexing.
     Otherwise, a formatter may fold title and paragraph together.
   * Always insert a blank line before an `@table' command and after an
     `@end table' command; but never insert a blank line after an
     `@table' command or before an `@end table' command.
     For example,
          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, ...
     Insert blank lines before and after `@itemize' ... `@end itemize'
     and `@enumerate' ... `@end enumerate' in the same way.
Complete phrases
................
   Complete phrases are easier to read than ...
   * Write entries in an itemized list as complete sentences; or at
     least, as complete phrases.  Incomplete expressions ... awkward
     ... like this.
   * Write the prefatory sentence or phrase for a multi-item list or
     table as a complete expression.  Do not write "You can set:";
     instead, write "You can set these variables:".  The former
     expression sounds cut off.
Editions, dates and versions
............................
   Write the edition and version numbers and date in three places in
every manual:
  1. In the first `@ifinfo' section, for people reading the Texinfo
     file.
  2. In the `@titlepage' section, for people reading the printed manual.
  3. In the `Top' node, for people reading the Info file.
Also, it helps to write a note before the first `@ifinfo' section to
explain what you are doing.
For example:
     @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.
     ...
--or use `@set' and `@value' (*note `@value' Example: value Example.).
Definition Commands
...................
   Definition commands are `@deffn', `@defun', `@defmac', and the like,
and enable you to write descriptions in a uniform format.
   * Write just one definition command for each entity you define with a
     definition command.  The automatic indexing feature creates an
     index entry that leads the reader to the definition.
   * Use `@table' ... `@end table' in an appendix that contains a
     summary of functions, not `@deffn' or other definition commands.
Capitalization
..............
   * Capitalize `Texinfo'; it is a name.  Do not write the `x' or `i'
     in upper case.
   * Capitalize `Info'; it is a name.
   * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
     `X'.  This command causes the formatters to typeset the name
     according to the wishes of Donald Knuth, who wrote TeX.
Spaces
......
   Do not use spaces to format a Texinfo file, except inside of
`@example' ... `@end example' and similar commands.
   For example, TeX fills the following:
         @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.
so it looks like this:
     `C-x v' `M-x vc-next-action' Perform the next logical operation on
     the version-controlled file corresponding to the current buffer.
In this case, the text should be formatted with `@table', `@item', and
`@itemx', to create a table.
@code, @samp, @var, and `---'
.............................
   * Use `@code' around Lisp symbols, including command names.  For
     example,
          The main function is @code{vc-next-action}, ...
   * Avoid putting letters such as `s' immediately after an `@code'.
     Such letters look bad.
   * Use `@var' around meta-variables.  Do not write angle brackets
     around them.
   * Use three hyphens in a row, `---', to indicate a long dash.  TeX
     typesets these as a long dash and the Info formatters re