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: 2013-03-17 17:39:34 UTC
If it seems to have gone quiet around here recently, that's only partly because it's summer, and the lure of the outdoors is stronger than staying in with my head in a chunk of code. I have been gnawing away at a major subproject: converting a real language based on yacc over to pacc. This has been quite an eye-opener! Read More...