.Dt MANUALS 7
.Os
.Sh Name
.
.Nm Practical UNIX Manuals
.Nd mdoc: structure, style, and composition
.\" (Quick Download: ePub | View: HTML)
.
.Sh Description
.
So you've written a UNIX utility, library, or driver—or started writing one—and you want to document your
work in manual form. What happens next?
.Pp
Practical UNIX Manuals: mdoc is a guide for writing well-formed and maintainable UNIX manuals
(
.Pp
manpages) in the mdoc language.
Why mdoc?
Foremost, formatters for the language are available by default on all modern UNIX installations and may be downloaded
for non-UNIX systems.
Furthermore, mdoc semantically annotates content, allowing for search and reference analysis of your
documentation.
For an analysis of mdoc and competing formats, refer to
Fixing on a
Standard Language for UNIX Manuals, published in the USENIX magazine.
.Pp
This guide is structured first as a series of tutorials, then as a guide to UNIX manual best practises. It is
not a reference! For that, refer to your local mdoc manual. It is, however, a work in
progress — if you have questions, comments, or suggestions, please contact the author, Kristaps Dzonsons.
.Pp
I also feature the History of UNIX Manpages, which chronicles the development of manpages from the 1960s
to the present day.
.
All content licensed under Creative Commons' Attribution Share-Alike: deriving works must attribute the author(s) and use a similar license. Citations should include the current version, 0.1.2, and date, 07 November 2011.
.Sh Practical UNIX Manuals: mdoc
.
.Ss On-line
.Bd -unfilled
.Lk Table of Contents: tree of HTML documents (XHTML)
.Lk Full Text: single HTML document (XHTML)
.Ed
.Ss Off-line
.Bd -unfilled
.Lk e-Book: e-Pub 2.0.1 archive
.Lk Document Tree: archive of HTML tree (XHTML)
.Lk Single Document: archive of HTML document (XHTML)
.Ed
.Sh The History of UNIX Manpages
.
.Ss On-line
.Bd -unfilled
.Lk Full Text: single HTML document
.Ed
.Sh News
.Bl -ohang
.It 07 November 2011, 0.1.2
Major addition of the History of UNIX Manpages study.
Also moved this page's Table of Contents to its own page (to free up space) and simplified this page.
Valuable editorial fixes thanks to an outside contributor: fixed History links and clarified several concepts in
the first few chapters among other improvements.
.
.It 04 September 2011, 0.0.27
Collected appendices into Appendices part. From now on, only minor editing before I
freeze a minor number release.
.El
.Lk See cvsweb for old news.
.
.
.\" Copyright © 2010—2011, Kristaps Dzonsons