488 lines
13 KiB
Text
488 lines
13 KiB
Text
---
|
|
title: Chapter 10. Manual Pages
|
|
prev: books/fdp-primer/po-translations
|
|
next: books/fdp-primer/writing-style
|
|
---
|
|
|
|
[[manual-pages]]
|
|
= Manual Pages
|
|
:doctype: book
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:icons: font
|
|
:sectnums:
|
|
:sectnumlevels: 6
|
|
:source-highlighter: rouge
|
|
:experimental:
|
|
:skip-front-matter:
|
|
:xrefstyle: basic
|
|
:relfileprefix: ../
|
|
:outfilesuffix:
|
|
:sectnumoffset: 10
|
|
|
|
toc::[]
|
|
|
|
[[manual-pages-introduction]]
|
|
== Introduction
|
|
|
|
_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.
|
|
|
|
[[manual-pages-sections]]
|
|
== Sections
|
|
|
|
Manual pages are grouped into _sections_. Each section contains manual pages for a specific category of documentation:
|
|
|
|
[.informaltable]
|
|
[cols="1,8", options="header"]
|
|
|===
|
|
| 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
|
|
|===
|
|
|
|
[[manual-pages-markup]]
|
|
== 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-pages-markup-sections]]
|
|
=== 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:
|
|
|
|
[.informaltable]
|
|
[cols="2,4", options="header"]
|
|
|===
|
|
| 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.
|
|
|
|
[[manual-pages-markup-macros]]
|
|
=== 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:
|
|
|
|
[.programlisting]
|
|
....
|
|
.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.
|
|
|
|
When rendered with the command `man ls`, the result displayed on the screen looks like this:
|
|
|
|
[.programlisting]
|
|
....
|
|
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.
|
|
|
|
[[manual-pages-markup-guidelines]]
|
|
=== Markup Guidelines
|
|
|
|
The man: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 link:{committers-guide}[Committer's Guide].
|
|
|
|
[[manual-pages-markup-tricks]]
|
|
=== Markup Tricks
|
|
|
|
Add a space before punctuation on a line with macros. Example:
|
|
|
|
[.programlisting]
|
|
....
|
|
.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,`.
|
|
|
|
[[manual-pages-markup-important-macros]]
|
|
=== Important Macros
|
|
|
|
Some very common macros will be shown here. For more usage examples, see man:mdoc[7], man:groff_mdoc[7], or search for actual use in [.filename]#/usr/shared/man/man*# directories. For example, to search for examples of the `.Bd`_Begin display_ macro:
|
|
|
|
[source,bash]
|
|
....
|
|
% find /usr/shared/man/man* | xargs zgrep '.Bd'
|
|
....
|
|
|
|
[[manual-pages-markup-important-macros-organizational]]
|
|
==== Organizational Macros
|
|
|
|
Some macros are used to define logical blocks of a manual page.
|
|
|
|
[.informaltable]
|
|
[cols="1,8", options="header"]
|
|
|===
|
|
| 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.
|
|
|===
|
|
|
|
[[manual-pages-markup-important-macros-inline]]
|
|
==== Inline Macros
|
|
|
|
Many macros are used to mark up inline text.
|
|
|
|
[.informaltable]
|
|
[cols="1,8", options="header"]
|
|
|===
|
|
| 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.
|
|
|
|
|`.Pa`
|
|
|Path to a file. Used to mark up filenames and directory paths.
|
|
|===
|
|
|
|
[[manual-pages-sample-structures]]
|
|
== Sample Manual Page Structures
|
|
|
|
This section shows minimal desired man page contents for several common categories of manual pages.
|
|
|
|
[[manual-pages-sample-structures-section-1-8]]
|
|
=== Section 1 or 8 Command
|
|
|
|
The preferred basic structure for a section 1 or 8 command:
|
|
|
|
[.programlisting]
|
|
....
|
|
.Dd August 25, 2017
|
|
.Dt EXAMPLECMD 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm examplecmd
|
|
.Nd "command to demonstrate section 1 and 8 man pages"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl v
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility does nothing except demonstrate a trivial but complete
|
|
manual page for a section 1 or 8 command.
|
|
.Sh SEE ALSO
|
|
.Xr exampleconf 5
|
|
.Sh AUTHORS
|
|
.An Firstname Lastname Aq Mt flastname@example.com
|
|
....
|
|
|
|
[[manual-pages-sample-structures-section-4]]
|
|
=== Section 4 Device Driver
|
|
|
|
The preferred basic structure for a section 4 device driver:
|
|
|
|
[.programlisting]
|
|
....
|
|
.Dd August 25, 2017
|
|
.Dt EXAMPLEDRIVER 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm exampledriver
|
|
.Nd "driver to demonstrate section 4 man pages"
|
|
.Sh SYNOPSIS
|
|
To compile this driver into the kernel, add this line to the
|
|
kernel configuration file:
|
|
.Bd -ragged -offset indent
|
|
.Cd "device exampledriver"
|
|
.Ed
|
|
.Pp
|
|
To load the driver as a module at boot, add this line to
|
|
.Xr loader.conf 5 :
|
|
.Bd -literal -offset indent
|
|
exampledriver_load="YES"
|
|
.Ed
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides an opportunity to show a skeleton or template
|
|
file for section 4 manual pages.
|
|
.Sh HARDWARE
|
|
The
|
|
.Nm
|
|
driver supports these cards from the aptly-named Nonexistent
|
|
Technologies:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
NT X149.2 (single and dual port)
|
|
.It
|
|
NT X149.8 (single port)
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
.Bl -diag
|
|
.It "flashing green light"
|
|
Something bad happened.
|
|
.It "flashing red light"
|
|
Something really bad happened.
|
|
.It "solid black light"
|
|
Power cord is unplugged.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr example 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
device driver first appeared in
|
|
.Fx 49.2 .
|
|
.Sh AUTHORS
|
|
.An Firstname Lastname Aq Mt flastname@example.com
|
|
....
|
|
|
|
[[manual-pages-sample-structures-section-5]]
|
|
=== Section 5 Configuration File
|
|
|
|
The preferred basic structure for a section 5 configuration file:
|
|
|
|
[.programlisting]
|
|
....
|
|
.Dd August 25, 2017
|
|
.Dt EXAMPLECONF 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm example.conf
|
|
.Nd "config file to demonstrate section 5 man pages"
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is an example configuration file.
|
|
.Sh SEE ALSO
|
|
.Xr example 8
|
|
.Sh AUTHORS
|
|
.An Firstname Lastname Aq Mt flastname@example.com
|
|
....
|
|
|
|
[[manual-pages-testing]]
|
|
== Testing
|
|
|
|
Testing a new manual page can be challenging. Fortunately there are some tools that can assist in the task. Some of them, like man:man[1], do not look in the current directory. It is a good idea to prefix the filename with `./` if the new manual page is in the current directory. An absolute path can also be used.
|
|
|
|
Use man:mandoc[1]'s linter to check for parsing errors:
|
|
|
|
[source,bash]
|
|
....
|
|
% mandoc -T lint ./mynewmanpage.8
|
|
....
|
|
|
|
Use package:textproc/igor[] to proofread the manual page:
|
|
|
|
[source,bash]
|
|
....
|
|
% igor ./mynewmanpage.8
|
|
....
|
|
|
|
Use man:man[1] to check the final result of your changes:
|
|
|
|
[source,bash]
|
|
....
|
|
% man ./mynewmanpage.8
|
|
....
|
|
|
|
You can use man:col[1] to filter the output of man:man[1] and get rid of the backspace characters before loading the result in your favorite editor for spell checking:
|
|
|
|
[source,bash]
|
|
....
|
|
% man ./mynewmanpage.8 | col -b | vim -R -
|
|
....
|
|
|
|
Spell-checking with fully-featured dictionaries is encouraged, and can be accomplished by using package:textproc/hunspell[] or package:textproc/aspell[] combined with package:textproc/en-hunspell[] or package:textproc/en-aspell[], respectively. For instance:
|
|
|
|
[source,bash]
|
|
....
|
|
% aspell check --lang=en --mode=nroff ./mynewmanpage.8
|
|
....
|
|
|
|
[[manual-pages-examples-as-templates]]
|
|
== Example Manual Pages to Use as Templates
|
|
|
|
Some manual pages are suitable as in-depth examples.
|
|
|
|
[.informaltable]
|
|
[cols="1,4", options="header"]
|
|
|===
|
|
| Manual Page
|
|
| Path to Source Location
|
|
|
|
|
|
|man:cp[1]
|
|
|[.filename]#/usr/src/bin/cp/cp.1#
|
|
|
|
|man:vt[4]
|
|
|[.filename]#/usr/src/shared/man/man4/vt.4#
|
|
|
|
|man:crontab[5]
|
|
|[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5#
|
|
|
|
|man:gpart[8]
|
|
|[.filename]#/usr/src/sbin/geom/class/part/gpart.8#
|
|
|===
|
|
|
|
[[manual-pages-resources]]
|
|
== Resources
|
|
|
|
Resources for manual page writers:
|
|
|
|
* man:man[1]
|
|
* man:mandoc[1]
|
|
* man:groff_mdoc[7]
|
|
* http://manpages.bsd.lv/mdoc.html[Practical UNIX Manuals: mdoc]
|
|
* http://manpages.bsd.lv/history.html[History of UNIX Manpages]
|