OpenBSD Journal
Home : : Add Story : : Archives : : About : : Create Account : : Login :
Practical UNIX Manuals: mdoc
Contributed by pitrh on Sat Aug 27 11:50:52 2011 (GMT)
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!


<< Slackathon 2011 report | Reply | Flattened | Expanded | 5.0 Preorders Open, Song Available, Great News Afoot >>

Threshold: Help

Related Links
more by pitrh

  Re: Practical UNIX Manuals: mdoc (mod 6/32)
by Venture37 (venture37) on Sat Aug 27 13:53:10 2011 (GMT)
  very nice, what did you use to generate the ePub files btw?
  [ Show thread ] [ Reply to this comment ] [ Mod Up ] [ Mod Down ]

  Re: Practical UNIX Manuals: mdoc (mod 7/31)
by Richard Toohey (richardtoohey) ( on Mon Aug 29 02:55:52 2011 (GMT)
  I'll have a read through when I can, just noticed this one on the front page:

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

  [ Show thread ] [ Reply to this comment ] [ Mod Up ] [ Mod Down ]

  Re: Practical UNIX Manuals: mdoc (mod 0/0)
by mxffiles ( on Tue Feb 7 08:08:54 2017 (GMT)
  This is a very good post which I really enjoy reading. It is not every day that I have the possibility to see something like this. Software mxf Software mxf converter free download to convert HD camcorder files. ts converter convert ts video files to avi, mp4, wmv, mov mts to avi mp4 mov mkv iMovie, FCP/FCE with mts converter, so to convert mts files for your PC and mobiles. mod converter and convert tod files just free download mod video converter. m2ts
  [ Show thread ] [ Reply to this comment ] [ Mod Up ] [ Mod Down ]

[ Home | Add Story | Archives | Polls | About ]

Copyright © 2004-2008 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 April 2nd 2004 as well as images and HTML templates were copied from the fabulous original with Jose's and Jim's kind permission. Some icons from used with permission from Kathleen. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. Search engine is ht://Dig. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]