Next: Sample Texinfo Files, Previous: @-Command Details, Up: Texinfo   [Contents][Index]

Appendix B Tips and Hints ¶

Writers of GNU manuals should consult GNU Manuals in GNU Coding Standards. Here are some other 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 …”.
• Design your manual so that it can be read sequentially, as far as possible. People tire of flipping back and forth to find information that should be presented to them as they need it.
• 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. You can write index entries as you write the body of the text, or write them afterwards.
• 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.
• Write the indexing commands that refer to a whole section immediately after the section command. Write the indexing commands that refer to a paragraph before that paragraph; this way, an index entry points to the first page of a paragraph that is split across pages.

  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.)

• Consistently capitalize the first word of every concept index entry, or else consistently use lowercase. Terse entries often call for lowercase; longer entries for capitalization. Whichever case convention you use, please use one or the other consistently! Mixing the two styles looks bad.
• Always capitalize or use uppercase for those words in an index for which this is proper, such as names of countries or acronyms. Always use the appropriate case for case-sensitive names, such as those in C or Lisp.

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.

Introducing New Terms ¶

• Introduce new terms so that a reader who does not know them can understand them from context; or write a definition for the term.

  For example, in the following, the terms “check in”, “register” and “delta” are all appearing for the first time; the example sentence should be rewritten so they are understandable.

  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.

• Use the @dfn command around a word being introduced, to indicate that the reader should not expect to know the meaning already, and should expect to learn the meaning from this passage.

Bad Examples ¶

Here are a few examples of bad writing to avoid:

When you are done editing the file, you must perform a @dfn{check in}.

In this example, say, “ … you must @dfn{check in} the new version.” That flows better.

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).

In this example, say, “… makes a unified interface such as VC mode possible.”

Periods Outside of Quotes ¶

Place periods and other punctuation marks outside of quotations, unless the punctuation is part of the quotation. This practice goes against some publishing conventions in the United States, 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).

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. It makes the source easier to read.
• Always insert a blank line before a @table command and after an @end table command; but never insert a blank line after an @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.

Spaces ¶

Do not use spaces to format a Texinfo file, except inside of @example … @end example and other literal environments and 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 a ‘@code’ command. 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. The Info formatter reduces three hyphens to two; a long dash is typeset in other output formats.

Program Invocation Nodes ¶

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, they are difficult for users to find.

So, there is a convention to name such sections with a phrase beginning with the word ‘Invoking’, as in ‘Invoking Emacs’; this way, users can find the section easily.

C functions ¶

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.

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.

Node Length ¶

Keep nodes (sections) to a reasonable length, whatever reasonable might be in the given context. Don’t hesitate to break up long nodes into subnodes and have an extensive tree structure; that’s what it’s there for. Many times, readers will probably try to find a single specific point in the manual, using search, indexing, or just plain guessing, rather than reading the whole thing from beginning to end.

You can use the texi-elements-by-size utility to see a list of all nodes (or sections) in the document, sorted by size (either lines or words), to find candidates for splitting. It’s in the util/ subdirectory of the Texinfo sources.

Capitalization ¶

• Capitalize “Texinfo”; it is a name. Do not write the ‘x’ or ‘i’ in uppercase.
• 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. (Likewise @LaTeX{} for LaTeX.)

And Finally … ¶

• Write notes for yourself at the very end of a Texinfo file after the @bye. None of the processors process text after the @bye; it is as if the text were within @ignore … @end ignore.