docs: Improve docs.

[subdirmk.git] / README

diff --git a/README b/README
index 6e4ac8e55a150e26e71b3a105e6e7f18ac24a3d3..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...
@@ -164,7 +172,7 @@ In more detail, with the various options for what comes next:
   directory  any      &/file    &,/file      &@/file         &@,/file
              several  & f g h   &, f g h     &@ f g h        &@, f g h
                                              
-  Top        lc                 &;file       &@.file         &@;file
+  Top        lc       file      &;file       &@.file         &@;file
   level      any      file      &;/file      &@./file        &@;/file
              several  f g h     &; f g h     &@. f g h       &@; f g h
              .mk.in   file      $(src)/file  $(abs)/file     $(abs_src)/file
@@ -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 | '/' ]