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

[Jouke Witteveen]

---
I think this covers the let function, but comments/suggestions are welcome in
case I missed something.

Regards,
- Jouke

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

diff --git a/doc/make.texi b/doc/make.texi
index 21573c0..f20f4fc 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,69 @@ 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 unpackinging.  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 string.  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
+
+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{foreach} 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 +7808,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 +12455,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