X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=README;h=6e4ac8e55a150e26e71b3a105e6e7f18ac24a3d3;hb=abb0c3933bb2092610fb6053c84b5296b8ce5341;hp=7fdeef52438817155503ce55cf72122e9e2b2050;hpb=08e0edf690f2ae65a6d2e82609da7562f55093ac;p=subdirmk.git

diff --git a/README b/README
index 7fdeef5..6e4ac8e 100644
--- a/README
+++ b/README
@@ -143,27 +143,31 @@ Summary of recommended directory reference syntaxes
 
 Path construction &-expansions, meanings summary:
 
-                      In build tree             In source tree
-  This directory        just &                    &,
-  Top level             &.  implies absolute      &;
-
-Adding `@' means "absolute path".  This is not needed with &. because
-there is never any need to use &. since it would expand to nothing.
-`/' 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.
-
-      Recommended     In build tree             In source tree
-             when     Relative  Absolute        Relative     Absolute
-                                          
-  This       lc       &file     &@file          &,file       &@,file
-  directory  any      &/file    &@/file         &,/file      &@,/file
-             several  & f g h   &@ f g h        &, f g h     &@, f g h
-
-  Top        lc                 &.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      $(abs)/file     $(src)/file  $(abs_src)/file
+                      Relative paths in...   Absolute paths in...
+                      build     source       build           source
+                                                       
+  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...
+             for      build     source       build           source
+                                                       
+  This       lc       &file     &,file       &@file          &@,file
+  directory  any      &/file    &,/file      &@/file         &@,/file
+             several  & f g h   &, f g h     &@ f g h        &@, f g h
+                                             
+  Top        lc                 &;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
 
 Substitution syntax
 -------------------
@@ -199,7 +203,7 @@ empty string).
 &;lc	=> $(top_srcdir)/lc		  &;/	=> $(top_srcdir)/
 
 &@lc	=> $(PWD)/sub/dir/lc		  &@/	=> $(PWD)/sub/dir/
-&.lc	=> $(PWD)/lc			  &./	=> $(PWD)/
+&@.lc	=> $(PWD)/lc			  &@./	=> $(PWD)/
 &@,lc	=> $(abs_top_srcdir)/sub/dir/lc	  &@,/	=> $(abs_top_srcdir)/sub/dir/
 &@;lc	=> $(abs_top_srcdir)/lc		  &@;/	=> $(abs_top_srcdir)/
 
@@ -207,16 +211,16 @@ In general:
     =	return subdir without delimiter (not allowed with `,' `;' `@')
     ,   pathname of this subdirectory in source tree
     ;   pathname of top level of source tree
-    .   pathname of this directory in build tree, implies absolute pathnames
-    @   absolute pathnames (forbidden with `.', must come first)
+    .   pathname of this directory in build tree, `@' must be specified
+    @   absolute pathnames
 
 So pathname syntax is a subset of:
     '&' [ '@' ] [ ',' | ';' | '.' ] [ lc | '/' ]
 
     To avoid incomprehensible .sd.mk files, some combinations are not
-    allowed.  For example `&@=./' would mean `$(PWD)/sub/dir' but can
-    be spelled `$(PWD)/&=/', but more normally the trailing / can be
-    tolerated, so use `&@/'.
+    allowed.  For example `&=./' would mean `.' and `&./' would be the
+    empty string.  Variations with `=' and one of `@' `,' `;' are
+    uncommon and must be written using make variables instead.
 
 &&		=>	&&		for convenience in shell runes
 \&		=>	&		general escaping mechanism