Re: [AD] Makedoc patch (was: 4.0.x branch)

[Bob <ohannessian@xxxxxxxxxx>]

Hi,

Sorry for sounding so harsh the first time - Didn't mean to :)

Stepan Roh wrote:
[snip]
> I don't want non-standard XML-based documentation format together with
> binary output format generators.

But, I am using standard XML! (refer to w3.org if you need confirmation). I 
am not using any particular documentation format (non of which are really 
standardized yet). This just means that Allegro will use it's own tags to 
describe what the docs will look like.

The rational for moving to some other format (Lisp s-expressions or XML) is 
to replace ._tx altogether (if you don't understand why, then take a look at 
makedoc.txt)

Finally, HTML and ASCII text are not binary formats (from a nice high-level 
point of view anyway).

[snip
> Why? Generating pretty documentation at the time of compiling seems like
> bad idea to me anyway. Only maintainers generating WIPs and CVS users
> (which should be experienced users anyway) will be forced to install
> necessary tools.

So why are we still doing it? Besides, pretty documentation is a big plus 
when you have a big lib (such as Allegro). It doesn't only add estethics, 
but also adds visual information to help better find the information that is 
being serached for. For example, if you wanted a description of the 
paramters to file_select_ex, you'd need to read through (and descypher) the 
entire paragraph. With visual 'hints', it's as easy as scanning the 
paragraph for italicized words.

Providing a documentation conversion tool is also useful for people writting 
add-ons - they'd like to use it too.


> There is no need to write full XML parser. There is lot of them around. I
> don't want to (and it is not even necessary) integrate it to Allegro (see
> previous paragraph).

It's nice and lite - you won't find many parsers that are so. It can also 
dual as a loader for the config file system (if we ever decide to go with *ML).

[snip]
> I wasn't talking about any DTD (you don't have to have DocBook XML
> installed to be able to produce and convert documentation), I was talking
> about using standard documentation format. You can produce a lot of
> formats with it and easily implement others.

Yes, I had a look at DocBook. It's a really nice standard provided one was 
writting a book :) Allegro's API documentation doesn't fit very well with 
DocBook's (overly convoluted IMHO) syntax.


> But most of all I hope that documentation format will stabilize in the
> near future and will not change every Allegro release (for example makedoc
> from 4.0.x will not produce documentation for 4.1.x and vice-versa).

That's only because of ._tx. If we used XML, then future parsers can also 
convert old documents. The reverse is also true, if unknown tags are ignored.


--
- Robert J Ohannessian
"Microsoft code is probably O(n^20)" (my CS prof)
http://pages.infinit.net/voidstar/