Prologue

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 of last modification.
• The canonical title of the manual.
• The manual category (manual section).
• Whether the manual relates to a particular hardware architecture.
• The relevant operating system.

Date

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.

Title

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.

Category

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:

1. Commands
2. System calls
3. Subroutines
4. Special files
5. File formats
6. User-maintained programs
7. Miscellaneous

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.

1: user utilities.

Most commands fall under this category. A user utility is usable by all operators of a UNIX system. Common examples: ls, man, cat.

2: system calls.

These are a special class of programming function, usually in C, that do not need header file or linking information. Common examples: open, close, write.

3: user programming functions.

Most functions fall under this category. A user programming function is available as standalone or library function, although some, such as the C library, need not be explicitly linked. Common examples: strcpy, isascii.

4: device interfaces.

This category is not as common as categories 1–3; in fact, not all systems use this section at all. When used, it consists of manuals for hardware device drivers. These manuals are usually tied to a particular architecture.

5: file formats.

This category is not as common as categories 1–3. When used, it consists of structure text file documentation. Common example: passwd.

6: games (and user utility miscellanea).

This category is not as common as categories 1–3, many systems do not come pre-supplied with games. When used, it refers to games or arcana utilities.

7: miscellaneous.

Introductory materials or general text. This category is common, but its contents vary from system to system.

8: administrative utilities.

This consists of utilities for system administration, which may not be accessible or executable by general users (see category 1). Common examples: dump, restore, fsck.

9: kernel programming functions.

This category is found on few operating systems. Where applicable, it consists of those functions used in operating system internal development (kernel development).

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.

Architecture

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.

Operating System

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.