X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=f79a280c5746f16954513f7023b5221deb2c0aef;hp=14cc5420f4783f5f4568c73e58eab1c48f5759f9;hb=2a5416707829f758cd5435e1d7c6075e633ef3fd;hpb=9178f4c13177c6436d08182e1649d8476b4c3b8a

diff --git a/README b/README
index 14cc542..f79a280 100644
--- 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
@@ -174,10 +181,11 @@ So pathname syntax is a subset of:
 	by the final warning state after processing all the toplevel
 	input files (including Final.sd.mk).
 
-&:local+global [&]VARIABLE ...
-	Suppresses the warning about seeing both VARIABLE and
-	&VARIABLE.  Any & specified in the RHS is redundant: this
-	always affects both versions identically.
+&:local+global [!][&]VARIABLE ...
+	Suppresses any warnings relating to forthcoming mentions
+	to VARIABLE or &VARIABLE, as applicable.  Scope ends at
+	the end of the current directory's Suffix.sd.mk.
+	Prefixing with ! removes [&]VARIABLE from the suppresion list.
 
 &:changequote NEWQUOTE
 	changes the escape sequence from & to literally NEWQUOTE
@@ -218,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:
 - - - - - - - - - - -
@@ -237,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
 ---------------------------------------------
@@ -411,7 +436,7 @@ far enough to regenerate a working set of makefiles.  If this happens
 just rerun ./config.status by hand.
 
 If you go back and forth between different versions of your code you
-can sometimes find that `make' complains that one of your Subdir.sd.mk
+can sometimes find that `make' complains that one of your Dir.sd.mk
 files is missing: typically, if iot was used and therefore a
 dependency in some other version of your code.  If you run `make
 clean' (or `make realclean') these dependencies are suppressed, which
@@ -517,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