[PATCH 2/2 V2] * doc/make.texi: Document the let function

[Jouke Witteveen]

---
Thanks to Martin Dorey for spotting a typo in the first version of this
patch.  I fixed a few others typos too in this revision.  This revision is
sent just so that the previous version does not get applied accidentally.
There may still be parts that could be improved.

The first patch in this series of two remains unchanged.

Regards,
- Jouke

 doc/make.texi | 88 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 76 insertions(+), 12 deletions(-)

diff --git a/doc/make.texi b/doc/make.texi
index 21573c0..4289f84 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -276,6 +276,7 @@ Functions for Transforming Text
 * Text Functions::              General-purpose text manipulation functions.
 * File Name Functions::         Functions for manipulating file names.
 * Conditional Functions::       Functions that implement conditions.
+* Let Function::                Lexically scoped variables.
 * Foreach Function::            Repeat some text with controlled variation.
 * File Function::               Write text to a file.
 * Call Function::               Expand a user-defined function.
@@ -7032,6 +7033,7 @@ be substituted.
 * Text Functions::              General-purpose text manipulation functions.
 * File Name Functions::         Functions for manipulating file names.
 * Conditional Functions::       Functions that implement conditions.
+* Let Function::                Lexically scoped variables.
 * Foreach Function::            Repeat some text with controlled variation.
 * File Function::               Write text to a file.
 * Call Function::               Expand a user-defined function.
@@ -7632,7 +7634,7 @@ the file names to refer to an existing file or directory. 
 Use the
 @code{wildcard} function to test for existence.
 @end table
 
-@node Conditional Functions, Foreach Function, File Name Functions, Functions
+@node Conditional Functions, Let Function, File Name Functions, Functions
 @section Functions for Conditionals
 @findex if
 @cindex conditional expansion
@@ -7685,14 +7687,70 @@ the result of the expansion is the expansion of the 
last argument.
 
 @end table
 
-@node Foreach Function, File Function, Conditional Functions, Functions
+@node Let Function, Foreach Function, Conditional Functions, Functions
+@section The @code{let} Function
+@findex let
+@cindex variables, lexically scoped
+
+The @code{let} function provides a means to limit the scope of a variable.
+The substitution of a value bound to a name in a @code{let} expression
+happens only in the text within the lexical scope defined by the @code{let}
+expression.
+
+Additionally, the @code{let} function enables list unpacking.  In that
+regard, it resembles the @code{read} command in the shell, @code{sh}.
+
+The syntax of the @code{let} function is:
+
+@example
+$(let @var{var} [@var{var} ...],@var{list},@var{text})
+@end example
+
+@noindent
+The first two arguments, the @var{var} list and @var{list}, are expanded
+before anything else is done; note that the last argument, @var{text}, is
+@strong{not} expanded at the same time.  Then, each word of the expanded
+value of @var{list} is bound to each of the variable names, @var{var}, in
+turn, with the final variable name being bound to the remainder of the
+expanded @var{list}.  In other words, the first word of @var{list} is
+bound to the first variable @var{var}, the second word to the second
+variable @var{var}, and so on.  If there are fewer words than there are
+@var{var} operands, the remaining @var{var}s are set to empty strings.  If
+there are fewer @var{var}s than words, the last @var{var} is set to what
+is left of the expanded @var{list} after the words bound to the earlier
+@var{var}s are removed.  After all variables are thus bound, @var{text} is
+expanded.
+
+This macro reverses the order of the words in the list that it is given as
+its first argument:
+
+@example
+reverse = $(let first rest,$1,$(if $(rest),$(call reverse,$(rest)) )$(first))
+@end example
+
+@noindent
+The @var{first} and @var{rest} variables are no longer available after the
+macro is expanded.  If variables by those names existed beforehand, they
+are not affected by the expansion of the @code{reverse} macro.
+
+The @code{let} function has no permanent effect on the variables
+@var{var}; their value and flavor after the @code{let} function call are
+the same as they were beforehand.  The values which are taken from
+@var{list} are in effect only temporarily, during the execution of
+@code{let}.  The variables @var{var} are simply-expanded variables
+during the execution of @code{let}.  If @var{var} was undefined
+before the @code{let} function call, it is undefined after the call.
+@xref{Flavors, ,The Two Flavors of Variables}.@refill
+
+@node Foreach Function, File Function, Let Function, Functions
 @section The @code{foreach} Function
 @findex foreach
 @cindex words, iterating over
 
-The @code{foreach} function is very different from other functions.  It
-causes one piece of text to be used repeatedly, each time with a different
-substitution performed on it.  It resembles the @code{for} command in the
+The @code{foreach} function is similar to the @code{let} function, but very
+different from other functions.  It causes one piece of text to be used
+repeatedly, each time with a different substitution performed on it.  The
+@code{foreach} function resembles the @code{for} command in the
 shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
 
 The syntax of the @code{foreach} function is:
@@ -7751,13 +7809,14 @@ actual function call to be re-expanded under the 
control of @code{foreach};
 a simply-expanded variable would not do, since @code{wildcard} would be
 called only once at the time of defining @code{find_files}.
 
-The @code{foreach} function has no permanent effect on the variable
-@var{var}; its value and flavor after the @code{foreach} function call are
-the same as they were beforehand.  The other values which are taken from
-@var{list} are in effect only temporarily, during the execution of
-@code{foreach}.  The variable @var{var} is a simply-expanded variable
-during the execution of @code{foreach}.  If @var{var} was undefined
-before the @code{foreach} function call, it is undefined after the call.
+Like the @code{let} function, the @code{foreach} function has no permanent
+effect on the variable @var{var}; its value and flavor after the
+@code{foreach} function call are the same as they were beforehand.  The
+other values which are taken from @var{list} are in effect only
+temporarily, during the execution of @code{foreach}.  The variable
+@var{var} is a simply-expanded variable during the execution of
+@code{foreach}.  If @var{var} was undefined before the @code{foreach}
+function call, it is undefined after the call.
 @xref{Flavors, ,The Two Flavors of Variables}.@refill
 
 You must take care when using complex variable expressions that result in
@@ -12397,6 +12456,11 @@ Return a string describing the flavor of the 
@code{make} variable
 @var{variable}.@*
 @xref{Flavor Function, , The @code{flavor} Function}.
 
+@item $(let @var{var} [@var{var} ...],@var{words},@var{text})
+Evaluate @var{text} with the @var{var}s bound to the words in
+@var{words}.@*
+@xref{Let Function, ,The @code{let} Function}.
+
 @item $(foreach @var{var},@var{words},@var{text})
 Evaluate @var{text} with @var{var} bound to each word in @var{words},
 and concatenate the results.@*
-- 
2.28.0