OpenBSD Journal

Practical UNIX Manuals: mdoc

Contributed by pitrh on from the deman(1)ding pages dept.

Kristaps Dzonsons wrote in with news on the documentation front:

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!

(Comments are closed)


  1. By Venture37 (venture37) on http://www.geeklan.co.uk

    very nice, what did you use to generate the ePub files btw?

    1. By Kristaps Dzonsons (kristaps) on

      > very nice, what did you use to generate the ePub files btw?

      See the "mdoc.epub" rule in the Makefile.

      Basically, I just zipped the files in the Right Way. I maintain the NCX (book.ncx) and OPF (book.xml converted to book.opf) file separately: the book is small enough that it's easy. The Makefile also has the magic for making separate XHTML files work together as one and so on.

  2. By Richard Toohey (richardtoohey) richardtoohey@paradise.net.nz on

    I'll have a read through when I can, just noticed this one on the front page:

    http://manpages.bsd.lv/

    "The guide is may be downloaded or viewed on-line. "

    Thanks.

    1. By Kristaps Dzonsons (kristaps) on

      > I'll have a read through when I can, just noticed this one on the front page: > > http://manpages.bsd.lv/ > > "The guide is may be downloaded or viewed on-line. "

      Richard,

      Thanks—fixed.

      Kristaps

Credits

Copyright © - Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]