README: Move the Warnings section up into what is going to be spec

[subdirmk.git] / README

diff --git a/README b/README
index dc22589750237d84c4e475f7f20f0d9cd4c40d2a..50bd4d3261898d8d96ff03bed8d6774212051f84 100644 (file)
--- a/README
+++ b/README
@@ -216,16 +216,15 @@ STUFF $ THINGS    ..      STUFF $$ THINGS
 
 &${..$..} =>   ${eval ${call ..$$..}}
        (matches { } pairs to find the end)
 
 &${..$..} =>   ${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:
 - - - - - - - - - - -
 
 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
 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
 
 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)).
 
 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
 ------------------
 
 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.)
 
 (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
 --------------------------------
 
 Subdirectory and variable naming
 --------------------------------