More docs updates

[subdirmk.git] / subdirmk / README

diff --git a/subdirmk/README b/subdirmk/README
index 1b249fd04b6f7914f7df0e63663b824eddc17bfa..8dfebc6818fdd9c7941740ec16bf5b4b64055e3b 100644 (file)
--- a/subdirmk/README
+++ b/subdirmk/README
@@ -5,7 +5,7 @@ Introduction
 ------------
 
 Peter Miller's 1997 essay _Recursive Make Considered Harmful_
-persuasively argues that it is better to arrannge to have a single
+persuasively argues that it is better to arrange to have a single
 make invocation with the project's complete dependency tree, rather
 than the currently conventional `$(MAKE) -C subdirectory' approach.
 
@@ -42,9 +42,9 @@ The Subdir.sd.mk's are filtered, fed through autoconf in the usual way
 (for @..@-substitutions) and included by one autogenerated toplevel
 makefile.
 
-So all of the input is combined and passed to one make invocation.  (A
-corollary is that there is no enforcement of the namespacing:
-discipline is required to prefix relevant variable names with &, etc.
+So all of the input is combined and passed to one make invocation.
+(A corollary is that there is no enforcement of the namespacing:
+discipline is required to prefix relevant variable names with &, etc.)
 
 Each subdirectory is also provided with an autogenerated `Makefile'
 which exists purely to capture ordinary make invocations and arrange
@@ -67,7 +67,7 @@ Each subdirectory has its own `all' target.  For example a
 subdirectory `src' has a target `src/all'.  The rules for these are
 automatically generated from the settings of the per-directory
 &TARGETS variables.  &TARGETS is magic in this way.  (In
-src/Subdir.sd.mk, &TARGES of course refers to a make variable called
+src/Subdir.sd.mk, &TARGETS of course refers to a make variable called
 src_TARGETS.)
 
 The `all' target in a parent directory is taken to imply the `all'
@@ -77,8 +77,9 @@ just type `make' in the toplevel, you are asking for `&all'
 (<subdir>/all) for every directory in the project.
 
 In a parallel build, the rules for all these various subdirectory
-targets may be in run in parallel: there is only one `make'
-invocation at a time.
+targets may be in run in parallel: there is only one `make' invocation
+at a time.  There is no sequencing between subdirectories, only been
+individual targets (as specified according to their dependencies).
 
 You can define other per-directory recursive targets too: simply
 mention (usually, by setting) the variable &TARGETS_zonk, or whatever.
@@ -109,6 +110,10 @@ If want to set global variables, such as CC, that should only be done
 once.  You can put them in your top-level Subdir.sd.mk, or a separate
 file you `include' and declare using SUBDIRMK_MAKEFILES.
 
+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'.
+
 Subdirectory templates `.sd.mk' vs plain autoconf templates `.mk.in'
 --------------------------------------------------------------------
 
@@ -174,7 +179,7 @@ empty string).
        Introduced by & followed by lwsp (space or tab).
        Each lwsp-separated non-ws word is prefixed by &/ &^/ &~/
        respectively.  No other & escapes are recognised.
-       This processing continues until a & preceded by lwsp,
+       This processing continues until & preceded by lwsp,
        or until EOL (the end of the line), or \ then EOL.
 
 &:<directive> <args>....
@@ -183,6 +188,7 @@ empty string).
 
 &:include filename             filename should usually be foo.sd.mk
 &:-include filename            tolerate nonexistent file
+       filenames are relative to $(top_srcdir)
 
 &!<lwsp>       disables & until EOL (and then disappears)