Re: [AD] new makedoc tool

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-06-29, Peter Wang <tjaden@xxxxxxxxxx> wrote:
> I don't think makedoc is actually unsalvagable, but a wiki-like syntax
> that doesn't lose too much information would be nicer.  And obviously
> using someone else's format and with tools maintained by somebody else
> is better, if we can easily extend the format to what we need.
> I'll check out asciidoc... and see about writing a backend :-)

DocBook and asciidoc backends are up.

Some examples of current output are here:

	http://web.aanet.com.au/tjaden/dev/makedoc/

I'm not sure about asciidoc as a primary format.  It's a little low
level so you lose some semantic information (e.g. it's not easy to just
extract the API entries).  You have to manually insert anchors.  Maybe
we could add what we need with macros or a preprocessor (it looks like
one will be required for quick-and-dirty man pages) but if it's too much
work...

It is also slow.  Converting the Allegro manual from asciidoc to HTML or
DocBook takes 40-50 seconds on my machine.  Converting DocBook to HTML
using Jade takes 5 minutes!  Is that normal?  Compare that to Test.hs,
which converts every ._tx file it can into the six formats it knows.
It takes about 7 seconds (compiled).

Peter