From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 16 Feb 2020 17:29:52 +0000 (+0000)
Subject: README: Fix documentation errors relating to &{ etc.
X-Git-Tag: v0.6.1~24^2~1
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=secnet.git;a=commitdiff_plain;h=e289974c7a39cad65013d4c5e472558b5669506d

README: Fix documentation errors relating to &{ etc.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---

diff --git a/README b/README
index bea3c1b..c30f3b6 100644
--- a/README
+++ b/README
@@ -229,15 +229,15 @@ STUFF $ THINGS	..	STUFF $$ THINGS
 &{..$..}	=>	${eval ${call ..$$..}}
 	(matches { } pairs to find the end)
 	content is $-doubled (unless it contains &$- to turn that off)
-	cf &(...), see "Convenience syntax for eval", below.
+	contrast &(...), see "Convenience syntax for call", below.
 
-Together &:macro and &${...} provide a more reasonable macro facility
+Together &:macro and &{...} provide a more reasonable macro facility
 than raw make.  They solve the problem that make expansions cannot
-directly generate multiple rules, variable, etc.; instead, `$(eval )'
+directly generate multiple rules, variables, etc.; instead, `$(eval )'
 must be used, but that re-expands the argument, meaning that all the
 literal text must be $-doubled.  This applies to the macro text and to
 the arguments.  Also `$(eval $(call ...))' is an unfortunate syntax.
-Hence &:macro and &${...}.
+Hence &:macro and &{...}.
 
 While dollar-doubling:
 - - - - - - - - - - -
@@ -253,7 +253,7 @@ 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.)
 
-Convenience syntax for eval
+Convenience syntax for call
 - - - - - - - - - - - - - -
 
 &(thing		=>	$(call thing
@@ -265,6 +265,10 @@ Convenience syntax for eval
 
 Unlike &{...}, this does not involve any dollar-doubling.
 
+Use this when the expansion is going to be a piece of text to be used
+as part of a rule, filename, etc.  When the expansion is top-level
+make text (eg, rules), use &:macro and &{...}.
+
 
 Invocation, "recursive" per-directory targets
 ---------------------------------------------