Re: [AD] new makedoc tool

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-06-29, Stepan Roh <stepan@xxxxxxxxxx> wrote:
> 
> On Wed, 29 Jun 2005, Elias Pschernig wrote:
> 
> >On Wed, 2005-06-29 at 18:20 +1000, Peter Wang wrote:
> >>Currently there exist [not completely polished] backends for:
> >>
> >>	- XML (that matches allegdoc.dtd, modulo extensions like subsections)
> >
> >I guess, backends can also use the XML then. I'm curious how it compares
> >to the XML produced by the perl, python and C versions :) Will try it
> >out on the weekend..

I think it follows more rigidly allegdoc.dtd when possible.

> >>	- LaTeX
> >
> >Yay. Finally, we can produce proper PDF output. Does it support
> >arbitrary hierarchy? (._tx needs support for that first of course) It
> >could then be used for things like tutorials..

Current makedoc syntax only supports @chapter, @heading and @hnode, but
it would be easy to support further nesting.

> >>	- man pages
> >>	- plain text
> >>
> >>A DocBook backend is on the way.  The parser doesn't handle thanks._tx
> >>or external files yet.
> >
> >Do you know if any of those can produce .info output?

This converts docbook to texinfo (and man) but I haven't tried it yet:

	http://docbook2x.sourceforge.net/

> 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.
> 
> Personally, I think _tx is a mess and needs to be placed into The 
> Retirement Home for Ugly Documentation Formats. XML-based formats are hard 
> to write (but easy to read, at least by computer). I agree with Elias that 
> Wiki-like format is a way to go. The question is: why invent some new 
> format? Why not use some existing? For example ELinks uses asciidoc which 
> is sort-of Wiki-like and extensible. May be worth checking.

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 :-)

Peter