Various markup forms and rendering programs have been used for manual pages. FreeBSD has used groff(7) and the newer mandoc(1). Most existing FreeBSD manual pages, and all new ones, use the mdoc(7) form of markup. This is a simple line-based markup that is reasonably expressive. It is mostly semantic: parts of text are marked up for what they are, rather than for how they should appear when rendered. There is some appearance-based markup which is usually best avoided.
Manual page source is usually interpreted and displayed to the screen interactively. The source files can be ordinary text files or compressed with gzip(1) to save space.
Manual pages can also be rendered to other formats, including PostScript for printing or PDF generation. See man(1).
Manual pages are composed of several standard sections. Each section has a title in upper case, and the sections for a particular type of manual page appear in a specific order. For a category 1 General Command manual page, the sections are:
| Section Name | Description |
|---|---|
| NAME | Name of the command |
| SYNOPSIS | Format of options and arguments |
| DESCRIPTION | Description of purpose and usage |
| ENVIRONMENT | Environment settings that affect operation |
| EXIT STATUS | Error codes returned on exit |
| EXAMPLES | Examples of usage |
| COMPATIBILITY | Compatibility with other implementations |
| SEE ALSO | Cross-reference to related manual pages |
| STANDARDS | Compatibility with standards like POSIX |
| HISTORY | History of implementation |
| BUGS | Known bugs |
| AUTHORS | People who created the command or wrote the manual page. |
Some sections are optional, and the combination of sections for a specific type of manual page vary. Examples of the most common types are shown later in this chapter.
mdoc(7) markup is based on macros. Lines that begin with a dot contain macro commands, each two or three letters long. For example, consider this portion of the ls(1) manual page:
.Dd December 1, 2015.Dt LS 1 .Sh NAME
.Nm ls .Nd list directory contents .Sh SYNOPSIS
.Nm
.Op Fl -libxo
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,
.Op Fl D Ar format
.Op Ar
.Sh DESCRIPTION
For each operand that names a .Ar file of a type other than directory, .Nm displays its name as well as any requested, associated information. For each operand that names a .Ar file of type directory, .Nm displays the names of files contained within that directory, as well as any requested, associated information.
| A Document date and Document title are defined. |
| A Section header for the NAME section is defined. Then the Name of the command and a one-line Name description are defined. |
| The SYNOPSIS section begins. This section describes the command-line options and arguments accepted. |
| Name ( |
| An Optional
Flag called |
| A long list of optional single-character flags are shown. |
| An optional |
| A final optional argument is defined. Because no name
is specified for the argument, the default of
|
| The Section header for the DESCRIPTION section is defined. |
When rendered with the command man ls,
the result displayed on the screen looks like this:
LS(1) FreeBSD General Commands Manual LS(1)
NAME
ls — list directory contents
SYNOPSIS
ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]
[file ...]
DESCRIPTION
For each operand that names a file of a type other than directory, ls
displays its name as well as any requested, associated information. For
each operand that names a file of type directory, ls displays the names
of files contained within that directory, as well as any requested,
associated information.Optional values are shown inside square brackets.
The mdoc(7) markup language is not very strict. For clarity and consistency, the FreeBSD Documentation project adds some additional style guidelines:
- Only the first letter of macros is upper case
Always use upper case for the first letter of a macro and lower case for the remaining letters.
- Begin new sentences on new lines
Start a new sentence on a new line, do not begin it on the same line as an existing sentence.
- Update
.Ddwhen making non-trivial changes to a manual page The Document date informs the reader about the last time the manual page was updated. It is important to update whenever non-trivial changes are made to the manual pages. Trivial changes like spelling or punctuation fixes that do not affect usage can be made without updating
.Dd.- Give examples
Show the reader examples when possible. Even trivial examples are valuable, because what is trivial to the writer is not necessarily trivial to the reader. Three examples are a good goal. A trivial example shows the minimal requirements, a serious example shows actual use, and an in-depth example demonstrates unusual or non-obvious functionality.
- Include the BSD license
Include the BSD license on new manual pages. The preferred license is available from the Committer's Guide.
Add a space before punctuation on a line with macros. Example:
.Sh SEE ALSO .Xr geom 4 , .Xr boot0cfg 8 , .Xr geom 8 , .Xr gptboot 8
Note how the commas at the end of the
.Xr lines have been placed after a space.
The .Xr macro expects two parameters to
follow it, the name of an external manual page, and a section
number. The space separates the punctuation from the section
number. Without the space, the external links would
incorrectly point to section 4, or
8,.
Some very common macros will be shown here. For
more usage examples, see mdoc(7), groff_mdoc(7), or
search for actual use in
/usr/share/man/man* directories. For
example, to search for examples of the .Bd
Begin display macro:
%find /usr/share/man/man* | xargs zgrep '.Bd'
Some macros are used to define logical blocks of a manual page.
| Organizational Macro | Use |
|---|---|
.Sh | Section header. Followed by the name of the section, traditionally all upper case. Think of these as chapter titles. |
.Ss | Subsection header. Followed by the name of
the subsection. Used to divide a
.Sh section into
subsections. |
.Bl | Begin list. Start a list of items. |
.El | End a list. |
.Bd | Begin display. Begin a special area of text, like an indented area. |
.Ed | End display. |