I recently learned how to write man pages
so that I could document
a bunch of little programs I’ve written.
Modern man pages are written in
whose documentation is also available from
differs from many other markup languages
rather than just
What this means is that
the markup indicates what something is,
not how to format it.
macro is used to indicate
rather than one of the macros
for bold, italic or underline.
This frees each author of having to choose
and enables consistent presentation
across different man pages.
Another advantage of semantic markup
is that information can be extracted from it.
can easily extract the name and short description
from each man page
thanks to the
I use the same information
to generate an Atom feed for these documents,
though in admittedly a much less robust way than
When it comes to actually writing
it can take some getting used to.
The language is of
so its syntax is very particular.
Macros cannot appear inline,
but must start on new lines
Sentences should likewise
always start on a new line.
Since I’m in the habit of writing with
semantic line breaks,
I actually find these requirements
fit in well.
The more frustrating syntax limitation to me
is the rule against empty lines.
it can be quite difficult to edit a lengthy document.
lines with only a
on them are allowed,
but this still causes visual noise.
To alleviate that,
I have a
syntax file for
which conceals the lone dots:
syntax match mdocBlank /^\.$/ conceal
let b:current_syntax = "mdoc"
It also adds the
section header and subsection header macros to the
option to make
aware of them.
I’ve found writing man pages pleasant and rewarding.
I’ve started writing other documents with
as you can see here.