Layout

An mdoc document body is divided into sections. The names and ordering of these sections is dictated by convention extending to the Version 1 AT&T UNIX Programmer's Manual.

The name section repeats the entry name and gives a very short description of its purpose.

The synopsis summarizes the use of the program being described. A few conventions are used, particularly in the Commands section. Underlined words are considered literals, and are typed just as they appear. Square brackets ([]) around an argument indicate that the argument is optional. When an argument is given as name, it always refers to a file name. Ellipses ... are used to show that the previous argument-prototype may be repeated. A final convention is used by the commands themselves. An argument beginning with a minus sign - is often taken to mean some sort of flag argument even if it appears in a position where a file name could appear. Therefore, it is unwise to have files whose names begin with -. The description section discusses in detail the subject at hand.

The files section gives the names of files which are built into the program.

A see also section gives pointers to related information.

A diagnostics section discusses the diagnostics that may be produced. This section tends to be as terse as the diagnostics themselves.

The bugs section gives known bugs and sometimes deficiencies. occasionally also the suggested fix is described.

The owner section gives the name of the person or persons to be consulted in case of difficulty. The rule has been that the last one to modify something owns it, so the owner is not necessarily the author.

These conventional sections haven't changed much over the years, although more sections have been added and several have changed with evolving UNIX operating system conventions. The full set of modern sections, and their order, is as follows.

NAME: Name of all documented components and a collective description.
SYNOPSIS: Calling syntax of the components.
DESCRIPTION: Description of all components. This constitutes the bulk of the manual.
IMPLEMENTATION NOTES: Specific notes on the implementation of a generic (e.g., standardised) component.
RETURN VALUES: Return values, if the components are functions.
ENVIRONMENT: Environmental variables affecting the components' operation.
FILES: Files affecting the components' operation.
EXIT STATUS: Exit status, if the components are commands.
EXAMPLES: Brief examples of invocation.
DIAGNOSIS: Error conditions, if a command or device driver.
ERRORS: Error conditions, if a function or library.
SEE ALSO: Links to other relevant manuals or references.
STANDARDS: Implemented or referenced standards.
HISTORY: A brief history of the components.
AUTHORS: The authors of the components.
CAVEATS: Caveats regarding the components' operation.
BUGS: Known bugs in the components.
SECURITY CONSIDERATIONS: Security precautions beyond the scope of the components.

Only the NAME and DESCRIPTION sections are required in the document body, although a SYNOPSIS should appear for most manuals as well.

Other sections may be necessary depending on the category. For example, RETURN VALUES is found for most category 3 and 2 manuals; while EXIT STATUS is found for most category 1, 6, and 8 manuals.

Contents

Home

History