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

B. Tips and Hints

Here are some tips for writing Texinfo documentation:

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:

Blank Lines

Complete Phrases

Complete phrases are easier to read than …

Editions, Dates and Versions

Include edition numbers, version numbers, and dates in the @copying text (for people reading the Texinfo file, and for the legal copyright in the output files). Then use @insertcopying in the @titlepage section (for people reading the printed output) and the Top node (for people reading the online output).

It is easiest to do this using @set and @value. See section @value Example, and GNU Sample Texts.

Definition Commands

Definition commands are @deffn, @defun, @defmac, and the like, and enable you to write descriptions in a uniform format.

Capitalization

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 ‘---

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

Introducing New Terms

@pxref

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.

Invoking from a Shell

You can invoke programs such as XEmacs, 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 XEmacs’; this way, users can find the section easily.

ANSI C Syntax

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.

Bad Examples

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.

And Finally …


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

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.