13.3.Â Markup

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).

Tip:

Testing a new manual page can be challenging when it is
not located in the normal manual page search path.
man(1) also does not look in the current directory. If
the new manual page is in the current directory, prefix
the filename with a ./:

%man ./mynewmanpage.8

An absolute path can also be used:

%man /home/xsmith/mynewmanpage.8

13.3.1.Â Manual Page Sections

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.

13.3.2.Â Macros

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 (.Nm) has
already been defined, and repeating it here just displays
the defined value in the text.

An OptionalFlag called -libxo
is shown. The Fl macro adds a dash to
the beginning of flags, so this appears in the manual
page as --libxo.

A long list of optional single-character flags are
shown.

An optional -D flag is defined. If
the -D flag is given, it must be
followed by an Argument. The
argument is a format, a string that
tells ls(1) what to display and how to display it.
Details on the format string are given later in the manual
page.

A final optional argument is defined. Because no name
is specified for the argument, the default of
file ... is used.

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.

13.3.3.Â Markup Guidelines

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 .Dd when 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.

13.3.4.Â Markup Tricks

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,.

13.3.5.Â Important Macros

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 .BdBegin display macro:

%find /usr/share/man/man* | xargs zgrep '.Bd'

13.3.5.1.Â Organizational Macros

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.

13.3.5.2.Â Inline Macros

Many macros are used to mark up inline text.

Inline Macro

Use

.Nm

Name. Called with a name as a parameter on the
first use, then used later without the parameter to
display the name that has already been
defined.