syntax: Support &: literal (for make `grouped' multiple targets)

[subdirmk.git] / README

diff --git a/README b/README
index b42356dc5e15ef63ee3bbb89b668551ddf2e964a..bea3c1b5ed053caaeb8078f821361add0778a0da 100644 (file)
--- a/README
+++ b/README
@@ -130,6 +130,10 @@ So pathname syntax is a subset of:
 &:<directive> <args>....
        recognised at start of line only (possibly after lwsp)
 
+&:             =>      &:
+       for make multiple targets syntax
+       recognised anywhere *except* start of line
+
 &:include filename             filename should usually be [&]foo.sd.mk
 &:-include filename            tolerate nonexistent file
        RHS is &-expanded but filenames are relative to the top
@@ -166,6 +170,9 @@ So pathname syntax is a subset of:
        `all' is extra special: every directory has an `all'
        target, which corresponds to &TARGETS.
 
+Directives
+- - - - -
+
 &:warn [!]WARNTAG ...
        Suppress (with !) or re-enable (without !) warnings tagged
        WARNTAG (see section `Warnings', below).  The suppression list
@@ -222,6 +229,7 @@ STUFF $ THINGS      ..      STUFF $$ THINGS
 &{..$..}       =>      ${eval ${call ..$$..}}
        (matches { } pairs to find the end)
        content is $-doubled (unless it contains &$- to turn that off)
+       cf &(...), see "Convenience syntax for eval", below.
 
 Together &:macro and &${...} provide a more reasonable macro facility
 than raw make.  They solve the problem that make expansions cannot
@@ -238,13 +246,25 @@ $ =>      $$      including $'s produced by other
                         &-expansions not mentioned here
 
 &\$    =>      $
-&$(    =>      ${      (expands to { } so it is useable for shell too)
+&$(    =>      $(
 &$NN   =>      ${NN}   where N are digits
 
 A few contexts do not support $-doubling, such as directive arguments
 or places where this might imply $-quadrupling.  (There is no way to
 get $-quadrupling.)
 
+Convenience syntax for eval
+- - - - - - - - - - - - - -
+
+&(thing                =>      $(call thing
+&( thing       =>      $(call thing
+       and specially:
+&(&lc          =>      $(call sub_dir_lc       or $(call TOP_lc
+&( &lc         =>      $(call sub_dir_lc       or $(call TOP_lc
+       even though lc would normally be thought a filename
+
+Unlike &{...}, this does not involve any dollar-doubling.
+
 
 Invocation, "recursive" per-directory targets
 ---------------------------------------------