Lately I'm playing with yet another personal project, and I would like to provide some man pages for it.
The fact is I love well written manuals, and I realized how I should put a better effort in documenting my software. I'm playing with GNU/Linux since 2003, I know how to write a decent piece of software, how could I not train myself with manpages?
To be fair, PFT — the best personal project I've made so far — is well documented, and rich of manpages. There's a trick though: it is written in Perl, and the manpages are generated from the comments as part of the regular Perl packaging (see perldoc).
But what if your software is in C? A colleague of mine, Anton, gave me the first input by suggesting that we should have manpages for our software, at work, where everything is in C++ or Python. We spoke a bit about this topic, and I started to think more about manuals.
Roff Troff Groff and such…
I started to teach myself how to use Groff, which is the GNU project's take on the original family of Troff software. I found it really bad.
No offense is intended to great Unix masters: I'm aware that this typesetting system is ancestral, not just made for manpages, and designed to fit 32 KiB of RAM! But I know LaTeX since long time, and of course a couple of modern markdowns: Groff looks so rough by comparison, so full of black magic, so poorly documented in general.
I value minimality a lot, but I also think it's quite expensive to work on a document whose source code resembles noise on a telephone line. I'm wondering if this is the real reason why the GNU project considers man pages to be optional 🤔.
My work colleague mentioned mdoc (from BSD) as the modern and more
"semantic" way of doing it. mdoc is basically an alternative set of
macros for Roff: it makes the job somewhat more reasonable and fosters
consistency in manuals. Everything would be so nice if only the Roff
typesetting was not part of it!
Choice of an alternative
At this point, I decided to seek around for alternatives. As it turns out there are many:
On Stack Overflow I've been suggested to use ronn, a tool for converting Markdown into manpages;
An undisclosed user suggested to write manuals in ReStructuredText, since they can be converted in manpages;
I also tried to use Asciidoc, driven by the fact that Much of the GitDocumentation is written in AsciiDoc.
My biased choice went on AsciiDoc, since I think Git is a quite cool project — Eh versions shit and doesnt afraid of anything —
Now let's write some manuals! In the next entry: Manpages in GNU Autotools.