wip docs, before rename .mk.in

diff --git a/subdirmk/README b/subdirmk/README
index 16a33e373d937567550c611ae4184cb662b90710..bebbf81709c844aa20d9198d84ac58dcdd02d796 100644 (file)
--- a/subdirmk/README
+++ b/subdirmk/README
@@ -53,8 +53,15 @@ for something suitable to happen.
 Where there are dependencies between subdirectories, each Subdir.mk.in
 can simply refer to files in other subdirectories directly.
 
-Per-directory targets, "recursion"
-----------------------------------
+Invocation, "recursive" per-directory targets
+---------------------------------------------
+
+Arrangements are made so that when you run `make foo' in a
+subdirectory, it is like running the whole toplevel makefile, from the
+toplevel, as `make subdir/foo'.  If `subdir/foo' is a file that might
+be built, that builds it.
+
+But `foo' can also be a conventional target like `all'.
 
 Each subdirectory has its own `all' target.  For example a
 subdirectory `src' has a target `src/all'.  The rules for these are
@@ -72,7 +79,42 @@ In a parallel build, the rules for all these various subdirectory
 targets may be in run in parallel: there is only one `make'
 invocation at a time.
 
-There may also be other 
+You can define other per-directory recursive targets too: simply
+mention (usually, by setting) the variable &TARGETS_zonk, or whatever.
+This will create a src/zonk target.  (&TARGETS is magic.)
+Unlike `all', these other targets only exist in areas of the project
+where at least something mentions them.  So for example, if
+&TARGETS_zonk is mentioned in src but not lib, `make zonk' in
+lib will fail.  If you want to make a target exist everywhere,
+mention its name in Perdir.mk.in (see below).
+
+Perdir.mk.in, inclusion
+-----------------------
+
+The file Perdir.mk.in in the toplevel of fthe source is automatically
+processed after each individual directory's Subdir.mk.in, and the
+&-substituted contents therefore appear once for each subdirectory.
+
+This lets you do per-directory boilerplate.  Some useful boilerplate
+is already provided in subdirmk, for you to reference like this:
+  &:include subdirmk/cdeps.mk.in
+  &:include subdirmk/clean.mk.in
+
+Note that you must use &:include, which is an include processed during
+the generation of the per-directory Subdir.mk files.  That ensures
+that the contents of these files is replicated, with appropriate
+per-directory substitutions, for each directory.
+
+Global definitions
+------------------
+
+If want to set global variables, such as CC
+
+
+
+  subdirmk/cdeps.mk.in
+  subdirmk/cdeps.mk.in
+