Sigh. Unix documentation, balkanization. Clearly we have to ship with a man page. It's a very long time since I've written anything in troff. For some recent projects, I've used pod to produce man pages. For one I wrote the documentation in XHTML and wrote a Haskell monadic combinator parser to output -man troff from that (OK, so that was insane).
These days, I am an enormous fan of reStructuredText (although not the language that spawned it), and I am on a one-person crusade to stop reST becoming the Betamax to markdown's VHS. So if all I want is a man page, then rst2man is the way to go.
But I am intending pacc eventually to be a GNU project. So I suppose I should write a texinfo manual, and use help2man to generate a minimal man page. I suppose I could quickly try the second half... And, y'know, it actually doesn't do too bad a job, if you can stand that sort of manual page. Hmm...
So here's one possibility: rst2texinfo exists. Come to that, the wonderful pandoc can do the job too (although I have found a few shortcomings in its reST parser (yes, I should fix them and submit patches)). But that's not going to work out well. For example, my reST markup uses a fixed-width font for command text and filenames, whereas texinfo distinguishes those.
I guess the Right Thing is to write a proper texinfo manual. I dislike the texinfo HTML output, but that can probably be smartened up with a modicum of XSLT and a sprinkling of CSS. And it does look nice on paper, of course. OK. I've avoided texinfo as far as possible for all these years, but let's give it a go.
Some random notes as I convert the reST documentation to texinfo.
I've now converted all the documentation I have into texinfo, and I'm reasonably pleased with the result. Of course, more documentation is needed, and the texinfo source can also be spruced up with nodes and index entries.
Last updated: 2015-05-24 19:45:26 UTC
One thing that pacc has lacked all the way along is users. It turns out to be really hard to write decent code without those darned users probing the dark corners. Read More...
I finally got round to implementing a simple but highly useful feature in the language, which I'm calling default expressions. It's probably simplest to explain by showing the test case: Read More...