.Dd $Date: 2014/04/07 21:14:41 $
.Dt MANUALS 7
.Os
.ShName
.
.NmPractical UNIX Manuals
.Ndmdoc: structure, style, and composition
.
.ShDescription
.
So you've written a UNIX utility, library, or driver—or have started writing one—and you want to
document your work in a manual. What happens next?
.Pp
Practical UNIX Manuals: mdoc is a guide for writing portable and maintainable UNIX manuals
(manpages
) in the mdoc language.
.Pp
Why
mdoc?
Formatters for the language are available by default on all modern UNIX installations and may be downloaded for
non-UNIX systems.
Furthermore,
mdoc annotates content semantically, not presentationally, producing consistent manpages
across systems.
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 book is structured first as a series of tutorials, then a guide to best practises: it is
not a reference! For that, refer to your local mdoc manual.
.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,
Kristaps Dzonsons, and use a similar license.
Citations should include the current version,
0.1.4, and date, 07 April 2014.
.
.ShPractical UNIX Manuals: mdoc
.
.SsOn-line
.Bd -unfilled
.Ed
.SsOff-line
.Bd -unfilled
.Lke-Book: e-Pub 2.0.1 archive
.Ed
.ShThe History of UNIX Manpages
.
.SsOn-line
.Bd -unfilled
.Ed
.ShNews
.Bl -ohang
.It07 April 2014, 0.1.4
Polished (editing) text in various places.
Cleaned up markup for more variable media.
Removed XHTML (of course, it's still used for the ePub) in favour of clean HTML5.
.
.It02 January 2012, 0.1.3
Added GNU troff archives and edited content in Part 3 as suggested by an outside contributor (thanks!).
.
.It07 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.
.El
.
.