X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=41110ce410ac8ca098cff5e28cbd182951fcc4ee;hp=b812f2782b06557d43101f1a642ebdf65570a018;hb=d1f413fb1910af153ed54281decab1696c7357b3;hpb=3fca8936b29ff6d0eb48fdd9c31a03abc1ec49e0

diff --git a/README b/README
index b812f27..41110ce 100644
--- a/README
+++ b/README
@@ -246,24 +246,6 @@ So pathname syntax is a subset of:
 &#	delete everything to end of line
 	(useful if the RHS contains unrecognised & constructions)
 
-&:changequote NEWQUOTE
-	changes the escape sequence from & to literally NEWQUOTE
-	NEWQUOTE may be any series of of non-whitespace characters,
-	and is terminated by EOL or lwsp.  The whole line is
-	discarded.
-
-	After this, write NEWQUOTE instead of &, everywhere.
-	The effect is unscoped and lasts until the next setting,
-	or until the end of the current directory's Suffix.sd.mk.
-	It takes effect on &:include'd files too, so maybe set
-	it back before using &:include.
-
-	Notably
-		NEWQUOTENEWQUOTE	=> NEWQUOTENEWQUOTE
-		NEWQUOTE\NEWQUOTE	=> NEWQUOTE
-		NEWQUOTE\$		=> $
-		NEWQUOTE:changequote &	set escape back to &
-
 &TARGETS_things
 	Handled specially.  If mentioned at the start of a line
 	(possibly following whitespace), declares that this
@@ -287,6 +269,37 @@ So pathname syntax is a subset of:
 	`all' is extra special: every directory has an `all'
 	target, which corresponds to &TARGETS.
 
+&:warn [!]WARNTAG ...
+	Suppress (with !) or re-enable (without !) warnings tagged
+	WARNTAG (see section `Warnings', below).  The suppression list
+	is reset at the start of processing in each subdirectory.
+	Warnings that appear at the end of processing are controlled
+	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.
+
+&:changequote NEWQUOTE
+	changes the escape sequence from & to literally NEWQUOTE
+	NEWQUOTE may be any series of of non-whitespace characters,
+	and is terminated by EOL or lwsp.  The whole line is
+	discarded.
+
+	After this, write NEWQUOTE instead of &, everywhere.
+	The effect is unscoped and lasts until the next setting,
+	or until the end of the current directory's Suffix.sd.mk.
+	It takes effect on &:include'd files too, so maybe set
+	it back before using &:include.
+
+	Notably
+		NEWQUOTENEWQUOTE	=> NEWQUOTENEWQUOTE
+		NEWQUOTE\NEWQUOTE	=> NEWQUOTE
+		NEWQUOTE\$		=> $
+		NEWQUOTE:changequote &	set escape back to &
+
 
 Dollar doubling and macro assistance
 ------------------------------------
@@ -373,6 +386,33 @@ 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 &.
+	(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
 --------------------------------