[SUBDIRMK RFC 7/7 option B] README: v2: Draft - Use / for variable names too. Use &. for just the name

[Ian Jackson]

Not implemented yet.

Signed-off-by: Ian Jackson <ijackson at chiark.greenend.org.uk>
---
 README | 52 +++++++++++++++++++++++++---------------------------
 1 file changed, 25 insertions(+), 27 deletions(-)

diff --git a/README b/README
index 6dd1a05..91b62d4 100644
--- a/README
+++ b/README
@@ -197,9 +197,8 @@ abs_src.)
 Substitution syntax
 -------------------
 
-In general & expands to the subdirectory name when used for a
-filename, and to the subdirectory name with / replaced with _ for
-variable names.
+In general & expands to the subdirectory name.  (`/' is legal in make
+variable names.)
 
 Note that & is processed *even in makefile comments*.  The substitutor
 does not understand make syntax, or shell syntax, at all.  However,
@@ -209,36 +208,37 @@ are common in makefiles.
 In the notation below, we suppose that the substitution is being in
 done in a subdirectory sub/dir of the source tree.  In the RH column
 we describe the expansion at the top level, which is often a special
-case (in general in variable names we call that TOP rather than the
-empty string).
+case.  (Even in variable names: top level's start `./'.)
 
-&CAPS		=>	sub_dir_CAPS			or TOP_CAPS
-&lc		=>	sub/dir/lc			or lc
-	Here CAPS is any ASCII letter A-Z and lc is a-z.
-	The assumption is that filenames are usually lowercase and
-	variables usually uppercase.  Otherwise, use another syntax:
-
-&_		=>	sub_dir_			or TOP_
-&=_		=>	sub_dir				or TOP
+&alpha		=>	sub/dir/alpha			or ./alpha
+	Here alpha is any ASCII letter A-Za-z.
+	The assumption is that filenames and variables usually
+	start with a letter.  Otherwise, use another syntax:
 
 &/		=>	sub/dir/			or nothing
-&=/		=>	sub/dir				or .
+&.		=>	sub/dir				or .
+	(This implies that `&./' works much like `&/'. &./ is
+	suitable for variable name construction in a way &/ is not.)
 
-&^lc		=>	$(top_srcdir)/sub/dir/lc
+&^alpha		=>	$(top_srcdir)/sub/dir/alpha
 &^/		=>	$(top_srcdir)/sub/dir/
+&^.		=>	$(top_srcdir)/sub/dir
 
-&~lc		=>	$(top_srcdir)/lc
+&~alpha		=>	$(top_srcdir)/alpha
 &~/		=>	$(top_srcdir)/
+&~.		=>	$(top_srcdir)
 
 In general:
-    =	return subdir without delimiter (not allowed with `^' `~')
     ^   pathname of this subdirectory in source tree
     ~   pathname of top level of source tree
-    /	terminates the escape (needed if next is not lwsp or space)
+    /	terminates the escape (needed if next is not lwsp, alpha or `.')
+    .	terminates the escape, gives subdir without /
   lwsp  starts multi-word processing (see below)
 
-So pathname syntax is a subset of:
-    '&' [ '^' | '~' ] [ lc | '/' ]
+&_		=>	ERROR (for compat with v1)
+
+So pathname and variable syntax is a subset of:
+    '&' [ '^' | '~' ] [ alpha... | '/' | '.' ]
 
 &&		=>	&&		for convenience in shell runes
 &@		=>	&		general escaping mechanism
@@ -247,11 +247,12 @@ So pathname syntax is a subset of:
 &$VARIABLE	$(sub/dir/VARIABLE)
 	VARIABLE is ASCII starting with a letter and matching \w+
 
-& thing thing... &
+&  thing thing... &
+&/ thing thing... &
 &^ thing thing... &
 &~ thing thing... &
 	Convenience syntax for prefixing multiple filenames.
-	Introduced by & followed by lwsp where lc could go.
+	Introduced by &... followed by lwsp where alpha could go.
 	Each lwsp-separated non-ws word is prefixed by &/ etc.
         etc. respectively.  No other & escapes are recognised.
 	This processing continues until & preceded by lwsp,
@@ -314,7 +315,7 @@ So pathname syntax is a subset of:
 	arranges that the *parent* will also have a `things' target
 	which recursively implies this directory's `things'.
 
-	Must be spelled exactly &TARGETS_things.  &_TARGETS_things,
+	Must be spelled exactly &TARGETS_things.  &/TARGETS_things,
 	for example, is not magic.  To make the target exist
 	without providing any prerequisites for it, write a line
 	containing just `&TARGETS_things +='.
@@ -356,13 +357,10 @@ namespace distinction between parts of variable names which come from
 subdirectory names, and parts that mean something else.
 
 So it is a good idea to be a bit careful with your directory naming.
-`TOP', names that contain `_', and names that are similar to parts of
+`.', names that contain `/', and names that are similar to parts of
 make variables (whether conventional ones, or ones used in your
 project) are best avoided.
 
-If you name your variables in ALL CAPS and your subdirectories in
-lower case with `-' rather than `_', there will be no confusion.
-
 Incorporating this into your project
 ------------------------------------
 
-- 
2.11.0