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

Default expressions

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

A new bug

Unfortunately, there are too many projects in this world, and pacc has been neglected for too long. However, I have been looking at one of those other projects recently, in fact, the one that convinced me I needed to write pacc in the first place! A new bug has turned up. (Hooray?) Read More...

See more news articles

feed