+However, actually writing a project's build system in a non-recursive
+style is not very ergonomic. The main difficulties are:
+ - constantly having to write out long file and directory names
+ - the lack of a per-directory make variable namespace means
+ long make variables (or namespace clashes)
+ - it is difficult to arrange that one can cd to a subdirectory
+ and say `make all' and have something reasonable happen
+ (to wit, build an appropriate subset)
+
+`subdirmk' is an attempt to solve these problems (and it also slightly
+alleviates some of the boilerplate needed to support out-of-tree
+builds well).
+
+Basic approach
+--------------
+
+The developer is expected to write a makefile fragment, in each
+relevant subdirectory, called `Subdir.sd.mk'.
+
+These fragments may contain ordinary make language.
+
+However, the sigil & is treated specially. By and large, it refers to
+`the current directory'. There are a variety of convenient
+constructions.
+
+The result is that to a large extent, the Subdir.sd.mk has an easy way
+to namespace its "local" make variables, and an easy way to refer to
+its "local" filenames.
+
+The Subdir.sd.mk's are filtered, fed through autoconf in the usual way
+(for @..@-substitutions) and included by one autogenerated toplevel
+makefile.
+
+So all of the input is combined and passed to one make invocation. (A
+corollary is that there is no enforcement of the namespacing:
+discipline is required to prefix relevant variable names with &, etc.
+
+Each subdirectory is also provided with an autogenerated `Makefile'
+which exists purely to capture ordinary make invocations and arrange
+for something suitable to happen.
+
+Where there are dependencies between subdirectories, each Subdir.sd.mk
+can simply refer to files in other subdirectories directly.
+
+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
+automatically generated from the settings of the per-directory
+&TARGETS variables. &TARGETS is magic in this way. (In
+src/Subdir.sd.mk, &TARGES of course refers to a make variable called
+src_TARGETS.)
+
+The `all' target in a parent directory is taken to imply the `all'
+targets in all of its subdirectories, recursively. And in the
+autogenerated stub Makefiles, `all' is the default target. So if you
+just type `make' in the toplevel, you are asking for `&all'
+(<subdir>/all) for every directory in the project.
+
+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.
+
+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.
+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.sd.mk (see below).
+
+Perdir.sd.mk, inclusion
+-----------------------
+
+The file Perdir.sd.mk in the toplevel of fthe source is automatically
+processed after each individual directory's Subdir.sd.mk, 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.sd.mk
+ &:include subdirmk/clean.sd.mk
+For example you could put that in Perdir.sd.mk.
+
+Global definitions
+------------------
+
+If want to set global variables, such as CC, that should only be done
+once. You can put them in your top-level Subdir.sd.mk, or a separate
+file you `include' and declare using SUBDIRMK_MAKEFILES.
+
+Subdirectory templates `.sd.mk' vs plain autoconf templates `.mk.in'
+--------------------------------------------------------------------
+
+There are two kinds of template files.
+
+ Filename .sd.mk .mk.in
+
+ Processed by &-substitution, autoconf only
+ then autoconf
+
+ Instantiated Usu. once per subdir Once only
+
+ Need to be mentioned No, but Subdir.sd.mk All not in subdirmk/
+ in configure.ac? via SUBDIRMK_SUBDIRS via SUBDIRMK_MAKEFILES
+
+ How to include `&:include foo.sd.mk' `include foo.mk'
+ in all relevant .sd.mk in only one
+ (but not needed for Subdir.sd.mk
+ Subdir and Perdir)
+
+If you `include subdirmk/regen.mk', dependency management and
+automatic regeneration for all of this template substitution, and for
+config.status etc. is done for you.
+
+Substitution syntax
+-------------------
+
+In general & expands to the subdirectory name when used for a
+filename, and to the subdirectory name with / replaced with _ for
+variable names.
+
+Note that & is processed *even in makefile comments*. The substitutor
+does not understand make syntax, or shell syntax, at all. However,
+the substitution rules are chosen to work well with constructs which
+are common in makefiles.
+
+In the notation below, we suppose that the substitution is being in
+done in a subdirectory sub/dir of the source tree. In the RH column
+we describe the expansion at the top level, which is often a special
+case (in general in variable names we call that TOP rather than the
+empty string).
+
+&CAPS => sub_dir_CAPS or TOP_CAPS
+&lc => sub/dir/lc or lc
+ Here CAPS is any ASCII letter A-Z and lc is a-z.
+ The assumption is that filenames are usually lowercase and
+ variables usually uppercase. Otherwise, use another syntax:
+
+&_ => sub_dir_ or TOP_
+&/ => sub/dir/ or nothing
+&=_ => sub_dir or TOP
+&=/ => sub/dir or .
+&^ => $(top_srcdir)/sub/dir or $(top_srcdir)
+&~ => $(abs_top_srcdir)/sub/dir or $(abs_top_srcdir)
+
+&& => && for convenience in shell runes
+\& => & general escaping mechanism
+
+& thing thing... &
+& ^ thing thing... &
+& ~ thing thing... &
+ Convenience syntax for prefixing multiple filenames.
+ Introduced by & followed by lwsp (space or tab).
+ Each lwsp-separated non-ws word is prefixed by &/ &^/ &~/
+ respectively. No other & escapes are recognised.
+ This processing continues until a & preceded by lwsp,
+ or until EOL (the end of the line), or \ then EOL.