X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=README;h=6705b14b8b8ec77bacfd664f2862f588439a6196;hb=51c56a8542758518adbd0e4739d526d423d4a006;hp=278ebb4e100e03fe237d041445665cff6b077f63;hpb=41b0c3f118d3ddd91662a439ff7c1e480d16151b;p=secnet.git

diff --git a/README b/README
index 278ebb4..6705b14 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,41 @@ 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.)
+
+
+Guides, hints, and further explanations
+=======================================
+
 Global definitions
 ------------------
 
@@ -321,6 +357,7 @@ If you need different settings of variables like CC for different
 subdirectories, you should probably do that with target-specific
 variable settings.  See the info node `(make) Target-specific'.
 
+
 Directory templates `.sd.mk' vs plain autoconf templates `.mk.in'
 --------------------------------------------------------------------
 
@@ -387,32 +424,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 &.
-	(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
 --------------------------------
@@ -491,7 +502,7 @@ will clear up the problem.
 
 
 Legal information
------------------
+=================
 
 subdirmk is
  Copyright 2019 Mark Wooding