The prologue consists at most of the Dd, Dt, and Os macros. These always occur at the beginning of a manual.
The only firm requirement of the mdoc prologue is that the Dd macro comes first: many formatting systems will read up to the first macro to determine the formatting language. If Dd is not encountered first, the mdoc format may not be recognised.
Following the Dd, the prologue is conventionally ordered as first Dt and then Os. The Os macro is usually left without arguments, meaning that the manual applies to the current system.
After parsing the document prologue, the following is known:
The date is specified by the Dd macro.
While no particular date format is required, it's best to use the month day, year format, where month is the month in English; day is the day of month; and year is the four-digit year. Arbitrary white-space may separate the tokens, which may also be quoted.
Example of canonical form:
Example of not zero-padded digit form:
Example of quoted-string form:
All of the above examples will normalise to the third of June, 1991. It's especially important that the month be in English, as not all operating systems support localisation.
Some formatters also support a special date format as follows:
This is usually used in conjunction with source-code control systems that automatically change the date. Consult your formatter's manual for whether it supports this feature.
A manual's title identifies the entire manual document. It is always specified in uppercase as the first argument of the Dt macro, which conventionally follows the initial Dd macro.
The title usually corresponds to the file-name of the document, but this is not necessarily the case.
In the case of a single-component manual, such as the manual for a single UNIX command or programming function, the title corresponds to the manual name as specified with the SYNOPSIS Nm macro argument.
In the event of multiple components, such as a programming library, the title usually corresponds to the library name. If multiple commands are specified, such as with aliased names, the canonical form should be used.
Example of a title for the ls utility:
Example of a title for the libgreeting function library, consisting of the hi and hello functions:
If the title is left unspecified by omitting the Dt macro, behaviour is undefined. Usually a formatter will default to an empty string or LOCAL. In general, however, a manual without Dt may be considered incomplete.
The category of a manual, sometimes called the manual section, specifies the type of component a manual describes. It is specified in the second argument of the Dt macro.
These categories are dictated by convention extending to the Version 1 AT&T UNIX Programmer's Manual.
This manual is divided into seven sections:
- System calls
- Special files
- File formats
- User-maintained programs
Commands are programs intended to be invoked directly by the user, in contradistinction to subroutines, which are intended to be called by the user's programs. Commands generally reside in directory bin (for binary programs).
These sections have been expanded and formalised in the intervening years, amounting to the following modern conventions.
There are several refinements to the numerical category convention. Perl, Fortran, and Tcl libraries are often grouped under category 3p, 3f, and 3tcl, respectively. Perl modules may also fall under 3pm. Tcl libraries are also found in the n category.
Although some common libraries are traditionally referred to with a custom suffix, such as 3ssl for the OpenSSL library, this notation is heavily discouraged.
Manuals for the X Window System, traditionally bundled with UNIX systems, are categorised under X11. Manuals for the popular X11R6 distribution of the X Window System may also be listed under X11R6.
The paper category historically consisted of longer papers, the draft category consists of draft manuals, unass consists of uncategorised manuals, and local consists of local system documentation. These categories are rarely used and should be avoided for portable, readable manuals.
Some manuals, especially those in category 4 or 9, relate only to a particular hardware architecture. This is a useful specifier in the machine-dependent manuals for category 9 manuals.
These use the optional third argument of the Dt macro.
For a list of possible architectures, consult your local documentation. A safe example is i386, for 32-bit x86-based systems; or amd64 for 64-bit AMD systems.
A device referring to a particular architecture uses this to explicitly note its relevant architecture. In normal manuals, this should not be used.
Similar to architecture, some manuals only pertain to a particular operating system. This system may be specified to the Os macro of the prologue.
If system is unspecified, the manual is assumed to apply to any operating system.
This form is useful when multiple operating systems have access to local-network administrative manuals, such as in a networked file-system environment. Otherwise, it is rarely used.
Last edited by $Author: kristaps $ on $Date: 2012/01/01 15:13:32 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.