Recursive targets for the user

[Ralf Wildenhues]

Somebody suggested to me (was that you, Ludo?) that Automake should
really allow the user to easily add recursive targets.

This is fairly trivial to implement, the biggest complication is name
calling.

So, here's the deal: currently, Automake has
  RECURSIVE_TARGETS
  RECURSIVE_CLEAN_TARGETS
  AM_RECURSIVE_TARGETS

where the last is the union of the first and then some more, none of
them are public interfaces, but at least the latter is used by, e.g.,
coreutils, to prevent invoking more than one of the recursive targets at
once with parallel make.  Lastly, the deal is that each $target requires
a non-pubic $target-am rule to actually do the work for the directory.

We cannot easily have Automake-defined variables to which the users add
to (with +=), so let's have two sets of variables.  Questions:

1) What to name them?
  RECURSIVE_USER_TARGETS
  RECURSIVE_USER_CLEAN_TARGETS
  ALL_RECURSIVE_USER_TARGETS

or have the USER_ before RECURSIVE_?

2) Whether to rename the above and reuse the names for the user (cleaner
interface but backward incompatible)?  So the internal one's would be,
say,

  am_RECURSIVE_TARGETS
  am_RECURSIVE_CLEAN_TARGETS
  am_ALL_RECURSIVE_TARGETS

3) Whether to document the s/$/-am/ rule for the per-directory target
so it then also holds for user-provided recursive rules.
(If yes, then we could share the rule code text between both.)

Comments?

Thanks,
Ralf