Here are some tips for writing Texinfo documentation:
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:
@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.)
@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 are easier to read than ...
Write the edition and version numbers and date in three places in every manual:
@ifinfo
section, for people reading the Texinfo file.
@titlepage
section, for people reading the printed manual.
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
(see section @value
Example).
Definition commands are @deffn
, @defun
,
@defmac
, and the like, and enable you to write descriptions in
a uniform format.
@table
... @end table
in an appendix that
contains a summary of functions, not @deffn
or other definition
commands.
@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.
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
around Lisp symbols, including command names.
For example,
The main function is @code{vc-next-action}, ...
@var
around meta-variables. Do not write angle brackets
around them.
Place periods and other punctuation marks outside of quotations, unless the punctuation is part of the quotation. This practice goes against convention, but enables the reader to distinguish between the contents of the quotation and the whole passage.
For example, you should write the following sentence with the period outside the end quotation marks:
Evidently, `au' is an abbreviation for "author".
since `au' does not serve as an abbreviation for `author.' (with a period following the word).
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
command around a word being introduced, to indicate
that the user should not expect to know the meaning already, and should
expect to learn the meaning from this passage.
Absolutely never use @pxref
except in the special context for
which it is designed: inside parentheses, with the closing parenthesis
following immediately after the closing brace. One formatter
automatically inserts closing punctuation and the other does not. This
means that the output looks right both in printed output and in an Info
file, but only when the command is used inside parentheses.
You can invoke programs such as Emacs, GCC, and GAWK from a shell. The documentation for each program should contain a section that describes this. Unfortunately, if the node names and titles for these sections are all different, readers find it hard to search for the section.
Name such sections with a phrase beginning with the word `Invoking ...', as in `Invoking Emacs'; this way users can find the section easily.
When you use @example
to describe a C function's calling
conventions, use the ANSI C syntax, like this:
void dld_init (char *@var{path});
And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with
@var
.
Avoid the obsolete style that looks like this:
#include <dld.h> dld_init (path) char *path;
Also, it is best to avoid writing #include
above the
declaration just to indicate that the function is declared in a
header file. The practice may give the misimpression that the
#include
belongs near the declaration of the function. Either
state explicitly which header file holds the declaration or, better
yet, name the header file used for a group of functions at the
beginning of the section that describes the functions.
Here are several examples of bad writing to avoid:
In this example, say, " ... you must @dfn
{check
in} the new version." That flows better.
When you are done editing the file, you must perform a
@dfn
{check in}.
In the following example, say, "... 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).
And in this example, you should specify what `it' refers to:
If you are working with other people, it assists in coordinating everyone's changes so they do not step on each other.
@bye
. None of the formatters process text after the
@bye
; it is as if the text were within @ignore
...
@end ignore
.