6.3.1 Manual pages

It is very important to keep a manual file (preferably in the UNIX man format) online for every program. A program that does not have an accompanying manual page is not complete. Of course there is always the inline help (help=) that every NEMO program has.

To a lesser degree this also applies to the public libraries. A template roff sample can be found in example.8. We encourage authors to have a MINIMUM set of sections in a man-page as listed below. The ones with a '*' are considered somewhat less important:

NAME

the name of the beast.

SYNOPSIS

command line format or function prototype, include files needed etc.

DESCRIPTION

maybe a few lines of what it does, or not does.

PARAMETERS

description of parameters, their meaning and default values. This usually applies to programs only.

EXAMPLES

(*) in case non-trivial, but recommended anyhow

DEBUG

(*) at what debug levels what output appears.

SEE ALSO

(*) references to similar functions, more info

BUGS

(*) one prefers not to have this of course

TIMING

(*) performance, dependence on parameters if non-trivial

STORAGE

(*) storage requirements - mostly of importance when programs allocate memory dynamically, or when applicable for the programmer.

LIMITATIONS

(*) does it have any obvious limitations?

AUTHOR

who wrote it (a little credit is in its place) and/or who is responsible.

FILES

(*) in case non-trivial

HISTORY

date, version numbers, why updated, by whom (when created)