English German (de_DE)
Chapter 10. Manual Pages
Manual Pages
_Manual pages_, commonly shortened to _man pages_, were conceived as readily-available reminders for command syntax, device driver details, or configuration file formats. They have become an extremely valuable quick-reference from the command line for users, system administrators, and programmers.
Although intended as reference material rather than tutorials, the EXAMPLES sections of manual pages often provide detailed use case.
Manual pages are generally shown interactively by the man:man[1] command. When the user types `man ls`, a search is performed for a manual page matching `ls`. The first matching result is displayed.
Sections
Manual pages are grouped into _sections_. Each section contains manual pages for a specific category of documentation:
| Section Number
| Category


|1
|General Commands

|2
|System Calls

|3
|Library Functions

|4
|Kernel Interfaces

|5
|File Formats

|6
|Games

|7
|Miscellaneous

|8
|System Manager

|9
|Kernel Developer
Markup
Various markup forms and rendering programs have been used for manual pages. FreeBSD has used man:groff[7] and the newer man:mandoc[1]. Most existing FreeBSD manual pages, and all new ones, use the man: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 man:gzip[1] to save space.
Manual pages can also be rendered to other formats, including PostScript for printing or PDF generation. See man:man[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.
Macros
man: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 man: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 _Optional_ _Flag_ 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 man: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. Since no name is specified for the argument, the default of `file ...` is used. The _Section header_ for the DESCRIPTION section is defined.