[AD] Pandoc

[Peter Wang <novalazy@xxxxxxxxxx>]

Hi,

Following up from the recent Allegro hack day conversation, I'm
proposing to use Pandoc for documentation.  It basically takes the same
approach as Haskell makedoc I proposed, but:

1. it reads in a *nice* lightweight syntax
2. it's maintained by someone else

http://johnmacfarlane.net/pandoc/
Apparently Windows binaries are available.

I've attached a small example of how we might use it.  Pandoc has some
deficiencies for us, but these are pretty minor:

- It doesn't support file includes.  My solution is to use a small
  script which looks for "@include FILE" markers and generates one big
  file for Pandoc to process.

- Cross reference support isn't so great, although good enough.  See
  inside the zip file for details.

- It doesn't yet output Texinfo.  I've mostly written an output driver
  which does.  It will be available in time.

- It doesn't output split HTML files.  We can add that support, or
  process each section as a separate document and combine them somehow.

Maybe we can convince the author to fix the first two as well.

A few days ago I added an output driver into my Haskell makedoc program
that can convert allegro._tx into a format readable by Pandoc, so we can
easily do a once-off conversion.

As Stepan Roh wrote in 2005:

    I think it is time to decide what to do with Allegro documentation. It has
    been discussed for so long, there is a new XML-based format, there are
    several makedoc tools. But we are still stuck with _tx and C makedoc.

So, that's that.

Peter

Attachment: pandoc_example.tar.gz
Description: application/tar-gz