chiark / gitweb /
~ian / subdirmk.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
README: v2: Draft - Use / for variable names too. Use &. for just the name
[subdirmk.git] / README
diff --git a/README b/README
index aa0424e39487c556574da733750a6a42fe734a44..91b62d481de802a297f86cf7de5c3613ee215762 100644 (file)
--- a/README
+++ b/README
@@ -197,9 +197,8 @@ abs_src.)
 Substitution syntax
 -------------------
 
 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,
 
 Note that & is processed *even in makefile comments*.  The substitutor
 does not understand make syntax, or shell syntax, at all.  However,
@@ -209,46 +208,51 @@ 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
 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 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/
+&^.            =>      $(top_srcdir)/sub/dir
 
 
-&~lc           =>      $(top_srcdir)/lc
+&~alpha                =>      $(top_srcdir)/alpha
 &~/            =>      $(top_srcdir)/
 &~/            =>      $(top_srcdir)/
+&~.            =>      $(top_srcdir)
 
 In general:
 
 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 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)
 
   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
 &&@            =>      &&               @ after any number of & vanishes
 
 
 &&             =>      &&              for convenience in shell runes
 &@             =>      &               general escaping mechanism
 &&@            =>      &&               @ after any number of & vanishes
 
-& thing thing... &
+&$VARIABLE     $(sub/dir/VARIABLE)
+       VARIABLE is ASCII starting with a letter and matching \w+
+
+&  thing thing... &
+&/ thing thing... &
 &^ thing thing... &
 &~ thing thing... &
        Convenience syntax for prefixing multiple filenames.
 &^ 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,
        Each lwsp-separated non-ws word is prefixed by &/ etc.
         etc. respectively.  No other & escapes are recognised.
        This processing continues until & preceded by lwsp,
@@ -311,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'.
 
        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 +='.
        for example, is not magic.  To make the target exist
        without providing any prerequisites for it, write a line
        containing just `&TARGETS_things +='.
@@ -319,6 +323,32 @@ So pathname syntax is a subset of:
        `all' is extra special: every directory has an `all'
        target, which corresponds to &TARGETS.
 
        `all' is extra special: every directory has an `all'
        target, which corresponds to &TARGETS.
 
+DRAFT - MACRO ASSISTANCE FACILITY
+---------------------------------
+
+Thanks to Mark Wooding.
+
+        &:macro NAME
+        STUFF
+        &:endm
+
+expands to
+
+        define %NAME
+        STUFF (with `$'s doubled except before a digit)
+        endef
+        NAME = $(eval $(call %NAME,$1,$2,$3,$4,$5,$6,$7,$8,$9))
+
+and
+
+        &(NAME ARG,ARG,...)
+
+expands to
+
+        $(call NAME,ARG,ARG,...)
+
+with `$'s doubled.
+
 Subdirectory and variable naming
 --------------------------------
 
 Subdirectory and variable naming
 --------------------------------
 
@@ -327,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.
 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.
 
 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
 ------------------------------------
 
 Incorporating this into your project
 ------------------------------------
 
Unnamed repository; edit this file 'description' to name the repository.