GNU Info

(standards.info)GNU Manuals

---

Next: Doc Strings and Manuals Up: Documentation

---

Enter node , (file) or (file)node

GNU Manuals
===========

   The preferred document format for the GNU system is the Texinfo
formatting language.  Every GNU package should (ideally) have
documentation in Texinfo both for reference and for learners.  Texinfo
makes it possible to produce a good quality formatted book, using TeX,
and to generate an Info file.  It is also possible to generate HTML
output from Texinfo source.  See the Texinfo manual, either the
hardcopy, or the on-line version available through `info' or the Emacs
Info subsystem (`C-h i').

   Nowadays some other formats such as Docbook and Sgmltexi can be
converted automatically into Texinfo.  It is ok to produce the Texinfo
documentation by conversion this way, as long as it gives good results.

   Programmers often find it most natural to structure the documentation
following the structure of the implementation, which they know.  But
this structure is not necessarily good for explaining how to use the
program; it may be irrelevant and confusing for a user.

   At every level, from the sentences in a paragraph to the grouping of
topics into separate manuals, the right way to structure documentation
is according to the concepts and questions that a user will have in mind
when reading it.  Sometimes this structure of ideas matches the
structure of the implementation of the software being documented--but
often they are different.  Often the most important part of learning to
write good documentation is learning to notice when you are structuring
the documentation like the implementation, and think about better
alternatives.

   For example, each program in the GNU system probably ought to be
documented in one manual; but this does not mean each program should
have its own manual.  That would be following the structure of the
implementation, rather than the structure that helps the user
understand.

   Instead, each manual should cover a coherent _topic_.  For example,
instead of a manual for `diff' and a manual for `diff3', we have one
manual for "comparison of files" which covers both of those programs,
as well as `cmp'.  By documenting these programs together, we can make
the whole subject clearer.

   The manual which discusses a program should certainly document all of
the program's command-line options and all of its commands.  It should
give examples of their use.  But don't organize the manual as a list of
features.  Instead, organize it logically, by subtopics.  Address the
questions that a user will ask when thinking about the job that the
program does.

   In general, a GNU manual should serve both as tutorial and reference.
It should be set up for convenient access to each topic through Info,
and for reading straight through (appendixes aside).  A GNU manual
should give a good introduction to a beginner reading through from the
start, and should also provide all the details that hackers want.  The
Bison manual is a good example of this--please take a look at it to see
what we mean.

   That is not as hard as it first sounds.  Arrange each chapter as a
logical breakdown of its topic, but order the sections, and write their
text, so that reading the chapter straight through makes sense.  Do
likewise when structuring the book into chapters, and when structuring a
section into paragraphs.  The watchword is, _at each point, address the
most fundamental and important issue raised by the preceding text._

   If necessary, add extra chapters at the beginning of the manual which
are purely tutorial and cover the basics of the subject.  These provide
the framework for a beginner to understand the rest of the manual.  The
Bison manual provides a good example of how to do this.

   To serve as a reference, a manual should have an Index that list all
the functions, variables, options, and important concepts that are part
of the program.  One combined Index should do for a short manual, but
sometimes for a complex package it is better to use multiple indices.
The Texinfo manual includes advice on preparing good index entries, see
Note: Making Index Entries, and see Note:
Defining the Entries of an Index.

   Don't use Unix man pages as a model for how to write GNU
documentation; most of them are terse, badly structured, and give
inadequate explanation of the underlying concepts.  (There are, of
course, some exceptions.)  Also, Unix man pages use a particular format
which is different from what we use in GNU manuals.

   Please include an email address in the manual for where to report
bugs _in the manual_.

   Please do not use the term "pathname" that is used in Unix
documentation; use "file name" (two words) instead.  We use the term
"path" only for search paths, which are lists of directory names.

   Please do not use the term "illegal" to refer to erroneous input to a
computer program.  Please use "invalid" for this, and reserve the term
"illegal" for activities punishable by law.