README: Document restriction on $-doubling and lack of -quadrupling

[subdirmk.git] / README

diff --git a/README b/README
index be1ece7c3d09e40d89170e7d0cb919e343f1369b..ad6c13ef3d53a67268cbf5c924e7ea0d6561ebce 100644 (file)
--- a/README
+++ b/README
@@ -158,47 +158,6 @@ 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.
 
-Tables of file reference syntaxes
----------------------------------
-
-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 Dir.sd.mk
-     relates, or relative to the project's top level ?
-
- (iii) Absolute or relative pathname ?  Usually relative pathnames
-     suffice.  Where an absolute pathname is needed, it can be built
-     out of &/ and an appropriate make variable such as $(PWD).
-
-Path construction &-expansions are built from the following:
-
-                      Relative paths in...
-                      build     source
-                                                       
-  This directory      &         &^
-  Top level           .         &~
-
-In more detail, with all the various options laid out:
-
-      Recommended     Relative paths in...   Absolute paths in...
-             for      build     source       build         source
-                                                       
-  This       lc       &file     &^file       $(PWD)/&file  $(abs_src)/&file
-  directory  any      &/file    &^/file      $(PWD)/&/file $(abs_src)/&/file
-             several  & f g h   &^ f g h     $(addprefix...)
-                                             
-  Top        lc       file      &~file
-  level      any      file      &~/file      $(PWD)/file   $(abs_src)/file
-             .mk.in   file      $(src)/file  $(PWD)/file   $(abs_src)/file
-             several  f g h     &~ f g h     $(addprefix...)
-
-(This assumes you have appropriate make variables src, PWD and
-abs_src.)
-
 Substitution syntax
 -------------------
 
@@ -363,6 +322,51 @@ $  =>      $$      including $'s produced by other
 &$NN   =>      $(NN)   where N are digits
 &$(    =>      $(
 
+A few contexts do not support $-doubling, such as directive arguments
+or places where this might imply $-quadrupling.  (There is no way to
+get $-quadrupling.)
+
+
+Tables of file reference syntaxes
+---------------------------------
+
+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 Dir.sd.mk
+     relates, or relative to the project's top level ?
+
+ (iii) Absolute or relative pathname ?  Usually relative pathnames
+     suffice.  Where an absolute pathname is needed, it can be built
+     out of &/ and an appropriate make variable such as $(PWD).
+
+Path construction &-expansions are built from the following:
+
+                      Relative paths in...
+                      build     source
+                                                       
+  This directory      &         &^
+  Top level           .         &~
+
+In more detail, with all the various options laid out:
+
+      Recommended     Relative paths in...   Absolute paths in...
+             for      build     source       build         source
+                                                       
+  This       lc       &file     &^file       $(PWD)/&file  $(abs_src)/&file
+  directory  any      &/file    &^/file      $(PWD)/&/file $(abs_src)/&/file
+             several  & f g h   &^ f g h     $(addprefix...)
+                                             
+  Top        lc       file      &~file
+  level      any      file      &~/file      $(PWD)/file   $(abs_src)/file
+             .mk.in   file      $(src)/file  $(PWD)/file   $(abs_src)/file
+             several  f g h     &~ f g h     $(addprefix...)
+
+(This assumes you have appropriate make variables src, PWD and
+abs_src.)
 
 Subdirectory and variable naming
 --------------------------------