Go to the previous, next section.
Please use Texinfo for documenting GNU programs. See the Texinfo manual, either the hardcopy or the version in the GNU Emacs Info subsystem (C-h i). See existing GNU Texinfo files (e.g., those under the `man/' directory in the GNU Emacs distribution) for examples.
The title page of the manual should state the version of the program which the manual applies to. The Top node of the manual should also contain this information. If the manual is changing more frequently than or independent of the program, also state a version number for the manual in both of these places.
The manual should document all command-line arguments and all commands. It should give examples of their use. But don't organize the manual as a list of features. Instead, organize it by the concepts a user will have before reaching that point in the manual. Address the goals that a user will have in mind, and explain how to accomplish them. Don't use Unix man pages as a model for how to write GNU documentation; they are a bad example to follow.
The manual should have a node named `program Invocation' or `Invoking program', where program stands for the name of the program being described, as you would type it in the shell to run the program. This node (together with its subnodes, if any) should describe the program's command line arguments and how to run it (the sort of information people would look in a man page for). Start with an `@example' containing a template for all the options and arguments that the program uses.
Alternatively, put a menu item in some menu whose item name fits one of the above patterns. This identifies the node which that item points to as the node for this purpose, regardless of the node's actual name.
There will be automatic features for specifying a program name and quickly reading just this part of its manual.
If one manual describes several programs, it should have such a node for each program described.
In addition to its manual, the package should have a file named `NEWS' which contains a list of user-visible changes worth mentioning. In each new release, add items to the front of the file and identify the version they pertain to. Don't discard old items; leave them in the file after the newer items. This way, a user upgrading from any previous version can see what is new.
If the `NEWS' file gets very long, move some of the older items into a file named `ONEWS' and put a note at the end referring the user to that file.
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 file names.
It is ok to supply a man page for the program as well as a Texinfo manual if you wish to. But keep in mind that supporting a man page requires continual effort, each time the program is changed. Any time you spend on the man page is time taken away from more useful things you could contribute.
Thus, even if a user volunteers to donate a man page, you may find this gift costly to accept. Unless you have time on your hands, it may be better to refuse the man page unless the same volunteer agrees to take full responsibility for maintaining it--so that you can wash your hands of it entirely. If the volunteer ceases to do the job, then don't feel obliged to pick it up yourself; it may be better to withdraw the man page until another volunteer offers to carry on with it.
Alternatively, if you expect the discrepancies to be small enough that the man page remains useful, put a prominent note near the beginning of the man page explaining that you don't maintain it and that the Texinfo manual is more authoritative, and describing how to access the Texinfo documentation.
Go to the previous, next section.