Preface

A utility without a manual is of no utility at all.

This is a guide for writing UNIX manuals in the mdoc language. If you're new to writing UNIX manuals, or you want to learn about best practises for high-quality manuals, this book may benefit your work.

To those unfamiliar with UNIX, mdoc is a language for documenting utilities, programming functions, file and wire formats, hardware device interfaces, and so on. By a language I mean a structured, machine-readable document format such as HTML, the primary language of web pages; or RTF, used by word processors. man is the utility for querying documents in mdoc and other languages, collectively called man pages.

The following, for example, is a fragment of man output for the cat command.

Why mdoc? After all, there are plenty of other UNIX manual languages out there, from the historical man to DocBook. In short, mdoc is:

• portable, as any modern UNIX system can format it without needing clumsy toolchains;
• expressive, capturing the semantic content of manpages instead of just presentation cues;
• concise, making line-based source control painless; and
• well-documented, well-supported, and actively maintained by a community of knowledgable developers.

No other format can boast all of these points at once.

In fact, although I've mentioned UNIX several times already, mdoc isn't exclusively tied to UNIX. Although UNIX and mdoc are historically linked, open source mdoc tools exist for any operating system. Furthermore, the documentation capabilities of mdoc apply to computing systems in general — not just UNIX.

In this book, however, I'll assume you are casually familiar with man and its output. This will allow us to focus on manuals with the same formatted output in mind. Thus, if you're unfamiliar with the man utility, this is a good time to read an introductory text on the subject (such as a UNIX beginner's guide), or at the very least, read the output of man man (the manual page of the man command).

This is not a canonical reference! The mdoc language is not standardised. For official reference, consult the manual distributed with your target computer system with man mdoc. This work primarily addresses the elements of mdoc common to any UNIX deployment, noting common pitfalls in portability.

Last edited by $Author: kristaps $ on $Date: 2011/11/04 01:06:28 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.