Re: [AD] including allegro.h and backward compability

[Eric Botcazou <ebotcazou@xxxxxxxxxx>]

> Sure. I grepped for ALLEGRO_NO_STD_HEADERS (or similar) to talk
> about it there, but it's not documented, so I left it.

You found *the* wrong example, ALLEGRO_NO_MAGIC_MAIN or ALLEGRO_USE_CONSOLE 
are right examples :-)

> I'd have expected that to be partially the point of api._tx.
> Listing that in the docs is not a good thing to do, as the doc
> should not know anything about old symbols, I think.

How do you want the user to know that a routine is deprecated if you don't 
tell him ? Several routines are already explicitly marked as "deprecated" in 
the docs.

But I think I see your point: you don't want to list a symbol that is not 
documented elsewhere in the docs. Sounds sensible to me. Then list only the 
routines documented as "deprecated" and use an elusive wording for the 
symbols belonging to the pre-4.0 era.

> How about I add a little section about the defines that one can
> use to control what the headers do, like the one I added and the
> one I mentionned above, and any others in the same vein ?

It already exists, it is dubbed "Difference between platforms". 
ALLEGRO_NO_STD_HEADERS should be document here, but I still think 
ALLEGRO_NO_COMPATIBILITY fits the  purpose of api._tx

-- 
Eric Botcazou