Re: [AD] Generate documentation about examples from their sources

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


> I'm attaching an incomplete preliminar patch which adds a new python
> script to the misc directory. This script could be run from time
> to time by the dictator or whoever packages the release files to
> update the new proposed documentation section about examples.

Really nice!

> Collateral damages: the infrequent @nonode command cannot be used
> with this patch, gives headaches for the .texi version. The .texi
> version has now fixed the problem of making cross references to
> commands which don't have a real node (like mouse_x/y/z).

Never mind I guess.

> The patch is incomplete because the script is not documented, it
> could be run in two operatonal modes (search some 'incremental'
> hardcoded keyword in the script), and there is a possibility left:
> it would be possible to reparse allegro._tx's xref sections and
> rewrite them to point to the examples automatically.  However,
> this could mean lot's of ex* references for each function (imagine
> allegro_init/install_allegro!).  So I don't know what to do. Ideas?

On the one hand, I'd rather not clutter the docs with too many references. On 
the other hand, a code sample is always interesting. Hence two suggestions:
- would it be feasible to specialize the example references, so that they 
appear in the HTML docs with a layout different from that of regular refs?
- would it be feasible to specify in the ._tx file a per-function limit on 
the number of example referenced (e.g 1 for allegro_init) ?

Just a minor nit in the patch:

+in the allegro/examples folder. You don't have to go through them in the

.. directory.


P.S: what of your patch against the configure machinery to dump the config 
options? It is nice too, so I'd like to have it in the next WIP. Could you 
apply it (even if you find it incomplete)?

-- 
Eric Botcazou




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