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.
Introduction to the mdoc language
This section will contain material helping beginners to get started with the mdoc(7)
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 provides much more information than this introduction.
Style guide for mdoc manuals
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, Ql)
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)
Reference manuals for the mdoc language
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)
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.
Details of the mdoc language
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.