X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=4493a0da2f146b5bf9121f09aa780ee9b3ee5cfa;hp=e303788b362856eb0474c4b2618c49b35ee32288;hb=b0bdaa30dd60890b5494fab1f3e7f5d70a8ceb8e;hpb=40c6be70076365e0bc2b69e4368b7338a2e452a8

diff --git a/README b/README
index e303788..4493a0d 100644
--- a/README
+++ b/README
@@ -88,13 +88,13 @@ empty string).
 
 &=		=>	sub_dir				or TOP
 
-&^lc		=>	$(top_srcdir)/sub/dir/lc
-&^/		=>	$(top_srcdir)/sub/dir/
-&^.		=>	$(top_srcdir)/sub/dir
+&^lc		=>	${top_srcdir}/sub/dir/lc
+&^/		=>	${top_srcdir}/sub/dir/
+&^.		=>	${top_srcdir}/sub/dir
 
-&~lc		=>	$(top_srcdir)/lc
-&~/		=>	$(top_srcdir)/
-&~.		=>	$(top_srcdir)
+&~lc		=>	${top_srcdir}/lc
+&~/		=>	${top_srcdir}/
+&~.		=>	${top_srcdir}
 
 In general:
     ^   pathname of this subdirectory in source tree
@@ -114,7 +114,7 @@ So pathname syntax is a subset of:
 &\$		=>	$		provided for $-doubling regimes
 &\NEWLINE				eats the newline and vanishes
 
-&$VARIABLE	=>	$(sub_dir_VARIABLE)	or $(TOP_VARIABLE)
+&$VARIABLE	=>	${sub_dir_VARIABLE}	or ${TOP_VARIABLE}
 	VARIABLE is ASCII starting with a letter and matching \w+
 
 & thing thing... &
@@ -174,10 +174,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
@@ -205,6 +206,10 @@ Dollar doubling and macro assistance
 &$-		Stops dollar-doubling
 	Both are idempotent and local to the file or context.
 
+This is useful both for make macrology involving $(eval ...), and
+possibly for helping write complicated recipes involving shell
+variables, inline Perl code, etc.
+
 Sometimes we will show $'s being doubled inside another construct.
 This means the content of the construct is $-doubled: $-doubling is
 locally enabled, and restored afterwards.
@@ -214,7 +219,7 @@ 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)
 
@@ -233,8 +238,8 @@ $	=>	$$	including $'s produced by other
 			 &-expansions not mentioned here
 
 &\$	=>	$
-&$NN	=>	$(NN)	where N are digits
-&$(	=>	$(
+&$(	=>	${	(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
@@ -334,7 +339,7 @@ suppressed with the &:warn directive.  The warning tags are:
 	interpret this as $(F)BAR.  It's normally better to write
 	it this way, at least if the variable expansion is followed
 	by more letters.  Note that &$FOO works differently to
-	raw make: it expands to $(sub_dir_FOO).
+	raw make: it expands to ${sub_dir_FOO}.
 
     broken-var-ref
         An attempt at variable expansion looking like $&...
@@ -407,7 +412,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