Re: [AD] new makedoc tool

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


On Wed, 2005-06-29 at 13:44 +0200, Stepan Roh wrote:

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

Well, as things look, we soon will have an improved _tx (i still would
like to rename the format to alex), and Haskell makedoc instead :)

> Personally, I think _tx is a mess and needs to be placed into The 
> Retirement Home for Ugly Documentation Formats.

I couldn't agree more when speaking about the current _tx.

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

Not sure. Looking at asciidoc, it has so many different stuff, and then,
has not the things we need (function prototypes, struct members, and so
on). It looks quite similiar to _tx though (looked at this example:
http://www.methods.co.nz/asciidoc/asciidoc.txt) - so if it would support
API documentation, I think it would be a good choice. But as it looks,
makedoc seems to be something nobody else has made yet, so we need our
own.

-- 
Elias Pschernig





Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/