Merge subdirmk 0.4

[secnet.git] / subdirmk / README

diff --git a/subdirmk/README b/subdirmk/README
index 3d18dc28294f0f2dfe87062cd8ca4660b3cd2219..f79a280c5746f16954513f7023b5221deb2c0aef 100644 (file)
--- a/subdirmk/README
+++ b/subdirmk/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
@@ -219,17 +226,18 @@ STUFF $ THINGS    ..      STUFF $$ THINGS
 &:endm         ..      endef
        NAME is processed for &
 
-&${..$..} =>   ${eval ${call ..$$..}}
+&{..$..}       =>      ${eval ${call ..$$..}}
        (matches { } pairs to find the end)
        content is $-doubled (unless it contains &$- to turn that off)
+       contrast &(...), see "Convenience syntax for call", below.
 
-Together &:macro and &${...} provide a more reasonable macro facility
+Together &:macro and &{...} provide a more reasonable macro facility
 than raw make.  They solve the problem that make expansions cannot
-directly generate multiple rules, variable, etc.; instead, `$(eval )'
+directly generate multiple rules, variables, etc.; instead, `$(eval )'
 must be used, but that re-expands the argument, meaning that all the
 literal text must be $-doubled.  This applies to the macro text and to
 the arguments.  Also `$(eval $(call ...))' is an unfortunate syntax.
-Hence &:macro and &${...}.
+Hence &:macro and &{...}.
 
 While dollar-doubling:
 - - - - - - - - - - -
@@ -238,13 +246,29 @@ $ =>      $$      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 call
+- - - - - - - - - - - - - -
+
+&(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.
+
+Use this when the expansion is going to be a piece of text to be used
+as part of a rule, filename, etc.  When the expansion is top-level
+make text (eg, rules), use &:macro and &{...}.
+
 
 Invocation, "recursive" per-directory targets
 ---------------------------------------------
@@ -518,8 +542,8 @@ Legal information
 =================
 
 subdirmk is
+ Copyright 2019-2020 Ian Jackson
  Copyright 2019 Mark Wooding
- Copyright 2019 Ian Jackson
 
     subdirmk and its example is free software; you can redistribute it
     and/or modify it under the terms of the GNU Library General Public