pacc logo

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: 2015-05-24 19:45:26 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 relief

Looking at _pacc_coords(), I noticed that it seemed to have the same realloc() bug that I'd just fixed in _pacc_result(). However, the "list of arrays" trick really wasn't going to work here. Read More...

Lists of arrays

In the previous post I talked about my ideas for avoiding a realloc-induced heisenbug. I've now implemented this, let me describe it. Read More...

See more news articles

feed