Missing info about commands, variables and attributes

After feeling a bit lost in using aap for some time I have finally
realised one thing that is missing from the documentation. I think it
would help me greatly in grokking how to use aap.

I would like to see info on what variables/attributes are used for each
command in the documentation. E.g. for :program I'd like to see
something like this:

 each C file is compiled like this:

  $(CC) $(CFLAGS) -o $(target) $(INCLUDE) $(source)

 each C++ file is compiled like this:

  $(CXX) $(CXXFLAGS) -o $(target) $(INCLUDE) $(source)

 and the final executable is linked with:

  $(CC) -o $(target) $(add_LIBS) $(LIBS) $(source)
 or if there was at least one C++ file among the sources with:
  $(CXX) -o $(target) $(add_LIBS) $(LIBS) $(source)

I'd also like to have it clearly marked what is a variable and what is
an attribute (and in the case of attributes: an attribute of what).

/M

P.S.
I found it very confusing that the following didn't do what I expected:

 :program { INCLUDE = -I../foo } bar : main.c

instead I needed to do this:

 INCLUDE = -I../foo
 :program bar : main.c

and $(INCLUDE) would then be used for _all_ compilations of C files
(which wasn't what I wanted).

-- 
Magnus Therning                    (OpenPGP: 0xAB4DFBA4)
[email protected]
http://magnus.therning.org/

You call it untidy, I call it LRU ordered
     -- Daniel Barlow

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)

iD8DBQFBA9JAiMWTaatN+6QRAlAbAKCTmm/xPrDFOV/7L6jqKbxQtzuxsgCdES89
wGmmHaoea1BwciQO2lVrmCs=
=gd0j
-----END PGP SIGNATURE-----