Hi,
How many of you want secretly to write or edit manpages but are scared
away by the language syntax?
How many have needed to write a manual, but just, you know, copied over
something similar, tweaked some words, and crossed your fingers?
How many can distantly remember searching the web for "how to write unix
manuals" and coming up with something by esr?
Or maybe you're infuriated by the relevance of <http://xkcd.com/912>.
If any of these applies to you, read on.
OpenBSD's mdoc(7) is THE REFERENCE for manpages. But the material is
dense owing to mdoc's twisty syntax. And after all, if you're just
starting on OpenBSD, or UNIX in general, it takes a bit of research to
even know mdoc(7) exists. You didn't learn to write C by reading the
EBNF, did you? No. You used K&R's book.
In short, not long after m2k10, I started to write a series of simple
guides to bridge the gap between "How do I?" and mdoc(7). It grew into
a manuscript, a friendly sort of manuscript. Then a sad orphaned
manuscript after being shot down by some publishers. So I slapped on a
friendly license and put it on the web. It's here:
http://manpages.bsd.lv/
And it needs love and care from more than just me. So if any of the
above appeals to you, please give it a look, and send your most scathing
criticism. It is NOT intended to replace mdoc(7)! But instead educate
what can't really be explained in a manual: conventions, nits, tools,
and so on. And it's very, very much a work in progress.
I marked this mail off-topic because it's not exactly an OpenBSD topic,
although the topic of manuals---OpenBSD's are the finest---is quite
relevant to anybody who has run "man". And the more knowledge of mdoc,
the better the manuals. But I do apologise if this is all in
frightfully bad form.
Thoughts?
Kristaps
