The source of a man page is a text file. When the man program is invoked it parses the text file using an nroff compatible program that interprets the man page according to a set of macro definitions. You must format your page with the proper macros so that man can display it properly. Darwin uses the -mdoc macro set as opposed to the older -man macro set. The examples below and in the templates all make use of macros in the -mdoc macro set. This is the preferred set of macros to use in a BSD based distribution.
For a more detailed description of the macros themselves and their usage see mdoc(7) and mdoc.samples(7).
Example macros:
.Sh NAME
.Op Fl Ar -verbose
.Nd does what it does
The macros above give three examples of macros found in the source code for man pages. Unlike XML tags, which always surround the appropriate text with opening and closing tags, nroff's -mdoc macros usually only flag the opening of the section of text that they format. The closing of a formating section is usually indicated by the end of a line. There are exceptions, like lists, but it is good to keep in mind that most formatting macros only extend their authority to the end of the line.
The -mdoc marcros are distinguished by two letter codes. Usually the first letter is uppercase and the second letter is lowercase. If a macro begins a line it must be preceded by a period (.).
In the first example above, .Sh denotes that NAME is a section header, man will then format it appropriately.
Often macros apply more than one formatting feature to a section of text. The second example above shows this. In that case .Op Fl AR applies three different rules to the -verbose text.
.Op declares that the text that follows (-verbose) is an option and that it should be formatted as such in the man page.
Fl designates the following text as a flag.
Ar designates it as an argument.
Since a macro has no closing tag other than the end of the line, a macro can apply formatting to multiple words. The final example above shows illustrates this. .Nd marks all that follows it ("does what it does") as being a description.
A man page is made up of multiple sections in the following form:
... .Dd March 24, 2001 .Os Darwin .Dt MAN_PAGE 1 .Sh NAME .Sh SYNOPSIS .Sh DESCRIPTION .Sh SEE ALSO ...
The -mdoc macros only requires the date (.Dd), document title (.Dt), and the operating system (.Os) macros to successfully format a man page. Of course these alone are not enough to give any useful information. You should provide at least the NAME, SYNOPSIS, DESCRIPTION, and SEE ALSO sections as well. Additional standard section headers are:
EXAMPLES
FILES
STANDARDS
HISTORY
AUTHORS
DIAGNOSTICS
ERRORS
BUGS
These should be used where appropriate. The sample templates make use of some of the alternate section headers by way of example. Additional user-defined section headers are also available if needed and should be delineated by the .Sh macro.
.Bd -literal -offset indent
int main(void) {
int i;
for(i=0; i>=0; i++)
printf("%d ", i);
}
.Ed
In certain man pages, it may be useful to include a code snippet as a means of clarifying the topic. You can do this by wrapping the code between a beginning .Bd -literal -offset indent macro and an ending .Ed macro as seen above.
.\" Full line comment .Sh NAME \" Partial line comment
Comments are delineated by the \" macro. As with all other macros, if it is at the beginning of a line, a period (.) must precede the \" macro. This macro causes the text that follows on that line to be ignored when the page is formatted for display. These are usually used to comment out licensing information. Generally they are not needed for anything else but are mentioned here as they appear in abundance in the templates. You can remove them without causing problems.