X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=50bd4d3261898d8d96ff03bed8d6774212051f84;hp=dc22589750237d84c4e475f7f20f0d9cd4c40d2a;hb=c4859585c93ccf44d33e657dec83eec9cfde0ab6;hpb=382bb6dfc4cdcbfd28a39bff0cf8009d6ad624d6;ds=sidebyside

diff --git a/README b/README
index dc22589..50bd4d3 100644
--- a/README
+++ b/README
@@ -216,16 +216,15 @@ STUFF $ THINGS	..	STUFF $$ THINGS
 
 &${..$..} =>	${eval ${call ..$$..}}
 	(matches { } pairs to find the end)
-	content is $-doubled (unless it contains $- to turn that off)
+	content is $-doubled (unless it contains &$- to turn that off)
 
-	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 )' 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 &${...}.
+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 )'
+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 &${...}.
 
 While dollar-doubling:
 - - - - - - - - - - -
@@ -300,7 +299,9 @@ includes.  So if you want to get in early and set global variables,
 put them near the top of Dir.sd.mk.
 
 The file Final.sd.mk in the toplevel directory is processed and
-included after all the other files.
+the result included after all the other files.  Its subdirmk
+filtering context inherits warning suppressions from the toplevel's
+Dir.sd.mk etc., but not anything else.
 
 subdirmk's filter script itself sets (only) these variables:
   top_srcdir
@@ -310,6 +311,37 @@ subdirmk's filter script itself sets (only) these variables:
 You are likely to want to define $(PWD), and shorter names for
 top_srdir and abs_top_srcdir (we suggest $(src) and $(abs_src)).
 
+Warnings
+--------
+
+subdirmk's `generate' program, which does the acual &-substitution,
+can produce some warnings about your .sd.mk files.  These can be
+suppressed with the &:warn directive.  The warning tags are:
+
+    local+global
+	The same VARNAME was used both with and without an & prefix.
+	This can be confusing.  Also, if you avoid this then you will
+	get a warning iff you accidentally leave off a needed &.
+	The generation of this warning depends on scanning your
+	makefile for things that look like variable references, which
+	subdirmk does not do completely perfectly.  Exciting make
+	syntax may evade this warning, or require suppressions.
+	(You can suppress this warning for a particular VARNAME with
+	the &:local+global directive.)
+
+    single-char-var
+	A variable expansion like $FBAR.  make's expansion rules
+	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).
+
+    unknown-warning
+	&:warn was used to try to enable a warning that this version
+	of subdirmk does not understand.  (Note that an attempt to
+	*dis*able an unknown warning is only reported if some other
+	warning was issued which might have been disabled.)
+
 Global definitions
 ------------------
 
@@ -387,36 +419,6 @@ In more detail, with all the various options laid out:
 (This assumes you have appropriate make variables src, PWD and
 abs_src.)
 
-Warnings
---------
-
-subdirmk's `generate' program, which does the acual &-substitution,
-can produce some warnings about your .sd.mk files.  These can be
-suppressed with the &:warn directive.  The warning tags are:
-
-    local+global
-	The same VARNAME was used both with and without an & prefix.
-	This can be confusing.  Also, if you avoid this then you will
-	get a warning iff you accidentally leave off a needed &.
-	The generation of this warning depends on scanning your
-	makefile for things that look like variable references, which
-	subdirmk does not do completely perfectly.  Exciting make
-	syntax may evade this warning, or require suppressions.
-	(You can suppress this warning for a particular VARNAME with
-	the &:local+global directive.)
-
-    single-char-var
-	A variable expansion like $FBAR.  make's expansion rules
-	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).
-
-    unknown-warning
-	&:warn was used to try to enable a warning that this version
-	of subdirmk does not understand.  (Note that an attempt to
-	*dis*able an unknown warning is only reported if some other
-	warning was issued which might have been disabled.)
 
 Subdirectory and variable naming
 --------------------------------