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

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.
September 3, 2015