Lightweight Markup Language & Roff

I was writing a small crappy OPML parser for uraniacast and by getting towards the end, I fell in a mood of reminding myself to write a manpage for it.

In the past, every time when I had to do that, I did what everyone did 20 years ago: typed man mdoc. The day before yesterday I looked at the calendar and realized that it was 2011. "Indeed", I said to myself, "you're a fool. What for such heroism? There are probably a plenty of LMLs on the internetz that can magically convert their input to roff. Right?"

Probably.

So I typed gem install ronn and started to fill the file that was intended to become the manpage.

Quite promptly, I noticed an inconvenience: in any software project no matter how small there are always some parts of the documentation that must be (a) in several files (b) equal to each other (c) up to date. A version number, for example. And you want that that parts came from 1 source to be inserted into n files every time when something like make release is happening.

There is 0 support for that in ronn. You can't suddenly write

<%= IO.read('../src/lib/uraniacast.tcl').
       match(/variable ver "(.+)"/)[1] %> 

right in the middle of document. All ronn does is producing roff.

"Fine", I said, "Let's bring in erb".

Now, we have 1 source file manpage.erb which must be transformed at least twice to become an accomplished object. This is like a butterfly formation [1]: starting with a larva (erb file), maturing as a pupa (markdown), releasing into an imago (roff).

So I dismissed that and start looking for another LML. "Maybe", I thought, "Maybe over there exists a combined version of the LML + a parody on a small macro language".

After spending some time wandering around another markdown implementations, I landed on asciidoc planet. A vain attempt.

It drew my attention because of (a) so called replacements (b) so called attributes. I thought that with a2x utility I could do it: define some 'replacements' in a configuration file and slip them into a2x. Sure enough, a2x doesn't give a damn about 'replacements' or 'attributes' if they occur in a literal block. Fuuuuuuck.

"Fine", I said, "Let's bring in m4".

Why dear g-d, why my every journey ends up with m4? I hate m4 & I cannot live without it. This is pathetic.

Once really addicted, users pursue writing of sophisticated m4 applications even to solve simple problems, devoting more time debugging their m4 scripts than doing real work.

—from GNU m4 manual.

[1]	Technically, the first step is an egg.