+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 & preceded by lwsp,
+ or until EOL (the end of the line), or \ then EOL.