As discussed previously, a section is begun by the Sh macro and continues until the end of file or another section.
What follows is a description of each required section: if your manual does not have the documented section, it should not be considered as well-formed. Do note, however, that some types of manuals lack the SYNOPSIS section.
The NAME section immediately follows the document prologue and is thus usually the first macro of the document body. It specifies the name of each documented component, and provides a brief description of the components as a whole.
The following is an example of the NAME section for a single utility, hi.
The Nd macro should consist of a single line without trailing punctuation or leading capitalisation. As a rule of thumb, this description should be a sentence clause in the imperative mood for commands and functions, or simply a noun phrase for file formats, devices, and miscellanea.
Example imperative:
Example noun phrase:
In the event of multiple named components, such as a function library or aliased commands, comma-separate each command but for the last. It's common to alphabetically order this listing.
Note that the punctuation should be separate from the macro argument. This allows the formatter to distinguish between the name and trailing punctuation.
The SYNOPSIS section, if specified, follows the NAME section. It specifies the calling syntax of a component, thus, it is necessary for functions and commands. The SYNOPSIS section has a layout dictated by convention, and depends upon the category.
For command manuals in category 1, 6, and 9, each command must have its full syntax stipulated.
This defines three optional arguments for the hi command: a flag, a flag with an argument, and an argument. Flags should be purely alphabetical, without regard to whether a flag takes an argument. Arguments should also be alphabetised.
Note that if your manual only documents one component, it's unnecessary to re-write the command name for Nm. If omitted, the last specified Nm in the NAME will be used.
Multiple commands are specified in the order they appear within the NAME section.
Since there are multiple Nm macros in the NAME section, it's necessary that we specify the name of each command. In this example, an additional command hi is specified, which has neither flags nor arguments.
Function libraries are more complicated, as they involve more diverse content. A function library SYNOPSIS section consists of all documented material, including header files, functions, variables, macros, and so on.
A minimum function manual consists of a single function call and the header file of its prototype (if in a language requiring header files, such as C):
The header file comes before those functions it describes. If one or more header files are required, list them in the order of inclusion in source files.
If multiple functions are documented, list them in the order they appear in the NAME section.
List any global variables with the Vt and/or Va macro following function prototypes.
Macro definitions, however, should come before the function prototypes. These use the Fd macro and must include the preprocessor directive for the macro.
Some manuals define a range of functions with differing header dependencies. In general it's not a good idea to group these within the same manual. However, if necessary, arrange the functions and variables underneath their header file In macros. These need not necessarily much with the NAME section ordering, but should be as close as possible.
This section documents the component itself, and is usually the longest. For commands, each command is described in detail along with its arguments. For functions, each function must be described along with its types and arguments.
A command or set of commands is documented in DESCRIPTION with a brief explanation of behaviour, default usage, then a list of arguments. Some utilities state default usage following the argument list; however, manpages beginning with these statements are more readable and economical.
If multiple commands are included, they should be listed in the order they appear in NAME and DESCRIPTION. Remember to specify a documented command, in this case, whenever invoking the Nm macro. Command exit statuses are documented in EXIT STATUS.
Functions do not share the The arguments are as follows convention that commands enjoy. Most often, a function is described in paragraph form.
A function with many variables, or complicated variables, may wish to choose the same listed-argument notation of commands.
Above all, you must be careful to document each argument to each function. Function return values are usually documented in RETURN VALUES.
| Contents | Next | Home | History |
Last edited by $Author: kristaps $ on $Date: 2012/01/01 15:13:32 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.