index —
extended documentation for the mdoc language
This collection of documents deals with the
mdoc(7)
language and tries to help
writing and maintaining manual pages. For tools
to
process and display manual pages, please go
back to the
mandoc homepage.
The target audience of this collection of documents are manual page
authors and people trying to fix bugs in existing
manuals.
This section will contain material helping beginners to get started with the
mdoc(7)
language.
- the first six lines of
a manual page source file (
Dd,
Dt,
Os,
Sh,
Nm,
Nd)
- recommended standard
sections (
Sh)
- synopsis for a
command line utility (
Nm,
Fl,
Ar,
Op)
- synopsis for
library functions (
In,
Ft, Fo,
Fa)
- escaping characters in
mdoc source files
- punctuation in mdoc
source files
- suppress horizontal
spacing (
Ns,
Sm)
For now, the mdoc tutorial
Practical UNIX
Manuals by
Kristaps Dzonsons provides
much more information than this introduction.
This section is intended for manual authors and maintainers familiar with basic
mdoc(7)
syntax and semantics. It explains a standard style for writing manuals.
Following
any common style across a wide range of
manuals helps users: Reading text in a good style you are already used to
facilitates understanding. The
particular style
proposed here has proven very successful in OpenBSD.
- multiple topics in one
manual page (
Dt,
Nm)
- command line
options (
Fl)
- command line
arguments (
Ar,
Cm)
- internal and
interactive commands (
Ic,
Cm)
- file system path names
(
Pa)
- displaying code
samples (
Bd,
Dl,
Dq)
- syntax spanning
multiple lines (
Bd)
- the SYNOPSIS section
in general (
Op,
Oo,
|)
- the SYNOPSIS
section for library functions (
Ft,
Fo,
Fa,
Fc,
Fn)
- marking up
function pointers (
Ft,
Fo,
Fa,
Fc)
- the ENVIRONMENT
section
- the FILES
section
- the EXIT STATUS
section (
Ex
-std)
- the SEE ALSO
section (
Xr,
Rs,
Lk)
- the STANDARDS
section (
St)
- the HISTORY
section
- the AUTHORS section
(
An,
Aq,
Mt)
The syntax and semantics of the mdoc language itself is documented in the
mdoc(7)
reference manual. Regarding the underlying roff language, a subset of features
relevant for manuals is documented in the
roff(7) and
mandoc_char(7)
manuals.
The
tbl(7) and
eqn(7)
languages can also be used in mdoc manuals. They should not be used lightly,
but only for individual manual pages having a pressing need for non-trivial
formulae or tables.
This section contains in-depth explanations and examples for intermediate to
advanced users of the mdoc language, going into more detail than what the
mdoc(7)
reference manual can reasonably cover. Robustness and portability of various
syntactic idioms are of particular concern here.
Beginners and experienced authors alike will occasionally wonder which macro is
best suited to mark up some given content, and then
an alphabetic index
may come in handy.
A collection of
exercises was first
developed for the
EuroBSDCon
2015
tutorial
on
mdoc.