-args are processed for & first
-&:include filename filename should usually be foo.mk.in
-&:-include filename
-
-CAPS is [A-Z][0-9_A-Z]*(?!\w)
-lc is [a-z][-+,0-9_a-z]*(?!\w)
-
-&!<spaces or tabs> disables & *until* EOL (and disappears)
-
-&!STUFF<lwsp> STUFF is recognised instead of &
- the terminating lwsp is discarded too
- may also occur at eol
-
-eg notably
- STUFF!& now & is recognised instead (ie back to normal)
- STUFFSTUFF STUFF
-
-eg
- &!@@@ @@@ is recognised instead of &
- @@@!& go back to &
-
-&TARGETS[_things] is handled specially
- must be spelled precisely this way
- if no _things, means _all
-
-Also, `all' is weird in that it is present even if not specified
+ recognised at start of line only (possibly after lwsp)
+ args are processed for &
+
+&:include filename filename should usually be foo.sd.mk
+&:-include filename tolerate nonexistent file
+
+&!<lwsp> disables & until EOL (and then disappears)
+
+&!STUFF
+ changes the escape sequence from & to literally STUFF
+ STUFF may be any series of of non-whitespace characters,
+ and is terminated by EOL or lwsp. STUFF and the lwsp
+ is discarded.
+
+ After this, write STUFF instead of &, everywhere.
+ The effect is global and lasts until the next setting.
+ It takes effect on &:include'd files too, so maybe set
+ it back before using &:include.
+
+ Notably
+ STUFFSTUFF => STUFF
+ \STUFF => STUFF
+ STUFF!& set escape back to &
+
+&TARGETS_things
+ Handled specially. If mentioned, declares that
+ this subdirectory ought to have a target `things'.
+ (`all' if not specified). The rule will be
+ &/things:: $(&TARGETS_things)
+
+ You may extend it by adding more :: rules for the target,
+ but the preferred style is to do things like this:
+ &TARGETS_check += & test-passed.stamp
+
+ It is important to mention &TARGETS_things at least once in
+ the context of each applicable directory, because it arranges
+ that the *parent* will also have a `things' target which
+ recursively implies this directory's `things'.
+
+ Must be spelled exactly &TARGETS_things. &_TARGETS_things,
+ for example, does not work. But mentioning it in a #-comment
+ *does* work because the & filter does not care about comments.
+
+ `all' is extra special: every directory has an `all'
+ target, which corresponds to &TARGETS.
+
+Subdirectory and variable naming
+--------------------------------
+
+The simple variable decoration scheme does not enforce a strict
+namespace distinction between parts of variable names which come from
+subdirectory names, and parts that mean something else.
+
+So it is a good idea to be a bit careful with your directory naming.
+`TOP', names that contain `_', and names that are similar to parts of
+make variables (whether conventional ones, or ones used in your
+project) are best avoided.
+
+If you name your variables in ALL CAPS and your subdirectories in
+lower case with `-' rather than `_', there will be no confusion.