Re: makedoc syntax (was Re: [AD] Screen destruction documentation update)

[Evert Glebbeek <eglebbk@xxxxxxxxxx>]

> I envision scenarios such as: a newbie on a.cc posts a problem
> regarding blit(). A veteran helps him out by linking to the manual and
> explaining something. Someone (perhaps the same person) then takes it
> upon himself to click on the linked blit() function and then click
> "edit" and make a clarification or update to the description. Trusted
> editors then get notified that there is a pending change. Assuming
> it's accepted, it instantly updates the manual and all downloadable
> versions of it - without having to wait a few months (or years) for
> the next Allegro release. That would *never* happen with an offline
> makedoc format. Once people start doing that and seeing themselves get
> credited with doc updates, they may just very will start proactively
> writing documentation.

I wasn't nescessarily thinking of documentation of existing functions when
I said it'd be too bothersome to keep disjunct code and documentation in
synch. I was more thinking of new functions and new API entries.

There's also a different reason for having a seperate Allegro manual with
the library, which is that it acts (can act) as a sort of `blue print' or
specification for what a function does. I know it's not always ideal in
that regard right now, but I think that for the future it could be.

I'm not saying that a second or `unofficial' manual with more
clarifications or code samples wouldn't be useful, I'm just saying that I
don't think it should fully replace the `official' one.

Evert