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

[Stepan Roh <stepan@xxxxxxxxxx>]

[I hope this mail will go into the list. I did not receive my previous one
before.]

On Wed, 20 Feb 2002, Bob wrote:

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

No problemo :-)

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

By "non-standard XML-based documentation" I meant "XML-based, but using
non-standard tags". And standard in this context means "widely used and
adopted documentation structure".

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

I know ._tx is not very ... ehm ... good :-)

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

By "binary output format generators" I meant "output generators which are
distributed as binary files (programs)". I will try to be more clear this
time :-)

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

Who knows? Because noone wants to change 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.

This clearly indicates bad documentation layout. See Javadoc's or
Doxygen's standard doclets how it should look like.

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

Using DocBook could solve this 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).

Yes, yes! XML-based configuration, please! I dreamt about it a long time
ago. But that's another story. Using your parser for config file handling
has nothing to do with documentation format.

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

Yes, that's true, today's Allegro documentation is just an API (with
exceptions to FAQ (direct support in DocBook :-) ), contributors, aHack
and maybe others). But maybe someone will write nice guides (remember
Vivace?) in the future and in that case you will have to add more tags, so
why not to move to something bigger today?

And for example documentation in Linux kernel is also API-based and is
written in DocBook SGML.

I think that Javadoc or Doxygen could be very useful here (of course
documentation will have to go into sources). You can also generate DocBook
from this.

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

I hope so, but makedoc from Allegro 4.1.x said to me something like
'@document_title missing' and gave up when I tried to generate
documentation for 4.0.x and 5.x. Are you sure this won't happen in the
future? (Warning: self-advertisment follows) My Allegro Source Browser
(http://srnet.cz/~stepan/allegro) now includes all three CVS modules:
4.0.x, 4.1.x and 5.x. (Self advertisment ends).

I don't want to advocate for DocBook much :-), but nice customizable
DocBook XSL which generates HTML and FOP (used to generate PS and PDF
outputs and RTF also) is already done. It is a good amount of work: will
someone do the same for Allegro's special XML-based documentation format?
If you fear the size of DocBook, the Simple DocBook with less tags is
available and it is  also possible to define our own subset of tags.

Have a nice day.

Stepan Roh