Documentation

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.

  • texinfo is about as annoying to write as pod, but of course it does more.
  • the TeX backend doesn't support Unicode, which is a pain as we really need to talk about the Unicode characters that pacc can use. I'm not going to worry about this too much, as it rather looks like there's a fix in Fedora rawhide already.

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

Donate

Support the development of pacc with a donation! We accept donations in BitCoin or via PayPal who handle almost any other form of payment.

News

  • Release: pacc-0.1 (wōkòu)

    I'm delighted to announce a new release of pacc, the packrat PEG parser generator for C. See the download page. Read More...

  • Tying the loop tighter

    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...

See more news articles

feed