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.

NAME

catconcatenate and print files

SYNOPSIS

cat [-benstuv] [file ...]

DESCRIPTION

The cat utility reads files sequentially, writing them to the standard output. The file operands are processed in command-line order. If file is a single dash (‘​-') or absent, cat reads from the standard input.

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

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.