Re: [AD] new makedoc tool

[Stepan Roh <stepan@xxxxxxxxxx>]

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..
>
> > 	- 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..
>
> > 	- 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?
>
> > I hope this tool will be taken into consideration if we will be shipping
> > pregenerated documentation in the future.
>
> I hope so too. And I think, when doing so, we should also revise
> the ._tx format slightly, there are just too many inconsistent things
> (which therefore make it hard to use). My idea is, it should be as easy
> to use as some wiki markup. The simpler the better.

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.

Peter's parser may be used for one-time conversion from _tx into extended 
asciidoc. Normal asciidoc utility would be used for converting it to HTML 
and DocBook which then could be converted to other formats. If some 
currently produced format can't be generated from DocBook, Peter's parser 
can be modified to convert asciidoc to these formats. Plain-text version 
(essentially asciidoc stripped off the markup by some simple utility) 
would be shipped with Allegro archives, other formats could be made 
downloadable.

Note, that makedoc-XML is not part of my "vision".

Have a nice day.

Stepan Roh