docs: Improve docs.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README b/README
index b4f9a1563d21b6277056ed6bc1cb93fc3a00cce8..ef839d56d9e7669abf3143e172ab0efbcb334f3a 100644 (file)
--- a/README
+++ b/README
@@ -28,15 +28,17 @@ Basic approach
 The developer is expected to write a makefile fragment, in each
 relevant subdirectory, called `Subdir.sd.mk'.
 
-These fragments may contain ordinary make language.
+These fragments may contain ordinary make language.  Unqualified
+filenames are relative to the build toplevel, and all commands all run
+there.
 
 However, the sigil & is treated specially.  By and large, it refers to
-`the current directory'.  There are a variety of convenient
-constructions.
+`the build directory corresponding to this .sd.mk file', etc.
+There are a variety of convenient constructions.
 
 The result is that to a large extent, the Subdir.sd.mk has an easy way
 to namespace its "local" make variables, and an easy way to refer to
-its "local" filenames.
+its "local" filenames (and filenames in general).
 
 The Subdir.sd.mk's are filtered, fed through autoconf in the usual way
 (for @..@-substitutions) and included by one autogenerated toplevel
@@ -138,10 +140,22 @@ If you `include subdirmk/regen.mk', dependency management and
 automatic regeneration for all of this template substitution, and for
 config.status etc. is done for you.
 
-Summary of recommended directory reference syntaxes
----------------------------------------------------
+Tables of file reference syntaxes
+---------------------------------
 
-Path construction &-expansions, meanings summary:
+In a nonrecursive makefile supporting out of tree builds there are
+three separate important distinctions between different file
+locations:
+
+ (i) In the build tree, or in the source tree ?
+
+ (ii) In (or relative to) the subdirectory to which this Subdir.sd.mk
+     relates, or relative to the project's top level ?
+
+ (iii) Absolute or relative pathname ?
+     (Usually relative pathnames suffice.)
+
+Path construction &-expansions are built from the following:
 
                       Relative paths in...   Absolute paths in...
                       build     source       build           source
@@ -149,12 +163,6 @@ Path construction &-expansions, meanings summary:
   This directory      &         &,           &@              &@,
   Top level           .         &;           &@.             &@;
 
-Adding `@' means "absolute path".  (`&.' is not allowed without @
-because just `&./' is a silly way of writing `.'.)  `/' terminates the
-escape (needed if the next thing is not a lowercase character, or
-space).  `=' means "just the value, no /".  Space starts multi-word
-processing.
-
 In more detail, with the various options for what comes next:
 
       Recommended     Relative paths in...   Absolute paths in...
@@ -213,6 +221,8 @@ In general:
     ;   pathname of top level of source tree
     .   pathname of this directory in build tree, `@' must be specified
     @   absolute pathnames
+    /  terminates the escape (needed if next is not lwsp or space)
+  lwsp  starts multi-word processing (see below)
 
 So pathname syntax is a subset of:
     '&' [ '@' ] [ ',' | ';' | '.' ] [ lc | '/' ]