In a previous article, it was said that UNIX manuals can look "indistinguishable from magic". This makes sense given the arcane syntax of mdoc, the language of OpenBSD's manuals.
But mdoc is just another language. Why is it so strange-looking when C or shell or Perl appears commonplace?
It occurred to me that a major problem with mdoc, and UNIX manuals in general, is a lack of introductory documentation. Unfamiliar things are scary. When writing my own first manual, years ago, about the only printed text I could find was Chapter 18: Documentation in esr's The Art of UNIX Programming. He puts it well: "Unix documentation is, at present, a mess.".
It's still true. But this doesn't help us much.
While mdoc(7) is the authoritative reference for OpenBSD's manpages (and applies to any mdoc formatter, like groff and Heirloom troff), it can be overwhelming. And while jmc@ is the iron first behind OpenBSD's superb manual quality, he can't help everybody. Anyhow, both of these assume one already knows what mdoc is, or whom to ask for help on the subject. This, sadly, isn't always the case!
It seems all that's left is to read the whole mdoc(7) reference (assuming one knows what to refer to in the first place!), copy an existing manual, or search the web for help (try it for a laugh). The best manual authors read the reference. The good ones copy [anything they can find]. The rest...
After kicking around the idea of a series of mdoc tutorials during m2k10, I started writing some tutorials. They sucked. Furthermore, it seemed that "tutorial" efforts would only continue to balkanise the field. There needed to be a book. So I begin writing again, but this time, writing a guide to mdoc as a general documentation format for UNIX. Not a reference — that would remain for mdoc(7) — but a slow introduction with examples and friendly colours.
Upon finishing a manuscript, unfortunately, the usual suspects in the technical-publishing field didn't seem to think this would sell. Maybe they're right (but maybe I just can't write). So instead I took the existing text and decided to just put it all online where it should have been in the first place.
This work has culminated in Practical UNIX Manuals: mdoc. Again, it's not a reference, but instead a gentle guide to the awesomeness of mdoc. More specifically, it's a bridge between "How do I..." and mdoc(7).
The problem is this: it needs your help. The mdoc language isn't big, but its conventions are finicky. So do you want to write manuals? Have you already, or have you tried? Do you have secret fears of those choppy mdoc sentence fragments and those ".Sh" and ".Bl -tag" terms? Fear no more, my friend. Read the guide, and when you're finished, put on your editor's hat (with the green visor) and be unsparing with your criticism. Which materials were useful to you? Which weren't? What's helpful, what's not? Even notes of misspellings, bad links, or ugly formatting help.
The book is in simple XHTML; the source can be downloaded. It has an e-Pub. Each page is linked to its CVS history — it's all there. So please help!