generate: Nested scope: Change `Eval' to `eval'

[subdirmk.git] / README

diff --git a/README b/README
index d750cb8e6daa40c7a6baf84f95bcdf6e699cd402..20658ae2adc3087e1f24db87cababc19aaa154b9 100644 (file)
--- a/README
+++ b/README
@@ -331,6 +331,28 @@ Dollar doubling and macro assistance
 &$-            Stops dollar-doubling
        Both are idempotent and local to the file or context.
 
+Sometimes we will show $'s being doubled inside another construct.
+This means the content of the construct is $-doubled: $-doubling is
+locally enabled, and restored afterwards.
+
+&:macro NAME   =>      define NAME
+STUFF $ THINGS ..      STUFF $$ THINGS
+&:endm         ..      endef
+       NAME is processed for &
+
+&${..$..} =>   ${eval ${call ..$$..}}
+       (matches { } pairs to find the end)
+       content is $-doubled (unless it contains $- to turn that off)
+
+       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 )' 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 &${...}.
+
 While dollar-doubling:
 - - - - - - - - - - -