From e5f6dc54b9d1454cd3d3a2152ff73802c7c4b2b0 Mon Sep 17 00:00:00 2001
From: Jouke Witteveen <j.witteveen@gmail.com>
Date: Fri, 25 Dec 2020 19:00:10 +0100
Subject: [PATCH] More correctly describe the scope of variables

* NEWS: Use "local" instead of the incorrect "lexically-scoped".
* doc/make.texi: Refer to let/foreach variables as local variables.
---
 NEWS          |  4 ++--
 doc/make.texi | 21 +++++++++++++++------
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/NEWS b/NEWS
index 5d71488c..53562605 100644
--- a/NEWS
+++ b/NEWS
@@ -35,8 +35,8 @@ https://sv.gnu.org/bugs/index.php?group=make&report_id=111&fix_release_id=109&se
   The configure script should verify the compiler has these features.
 
 * New feature: The $(let ...) function
-  This function allows user-defined functions to provide a lexically-scoped
-  set of variables: values can be assigned to these variables from within the
+  This function allows user-defined functions to define a set of local
+  variables: values can be assigned to these variables from within the
   user-defined function and they will not impact global variable assignments.
   Implementation provided by Jouke Witteveen <j.witteveen@gmail.com>
 
diff --git a/doc/make.texi b/doc/make.texi
index ce2c6e50..60c75d60 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -276,7 +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.
+* Let Function::                Local variables.
 * Foreach Function::            Repeat some text with controlled variation.
 * File Function::               Write text to a file.
 * Call Function::               Expand a user-defined function.
@@ -5204,7 +5204,9 @@ variables are called @dfn{macros}.)
 Variables and functions in all parts of a makefile are expanded when
 read, except for in recipes, the right-hand sides of variable
 definitions using @samp{=}, and the bodies of variable definitions
-using the @code{define} directive.@refill
+using the @code{define} directive.  The value a variable expands to is
+that of its most recent definition at the time of expansion.  In other
+words, variables are dynamically scoped.
 
 Variables can represent lists of file names, options to pass to compilers,
 programs to run, directories to look in for source files, directories to
@@ -5792,6 +5794,11 @@ You can specify a value in the makefile, either
 with an assignment (@pxref{Setting, ,Setting Variables}) or with a
 verbatim definition (@pxref{Multi-Line, ,Defining Multi-Line Variables}).@refill
 
+@item
+You can specify a short-lived value with the @code{let} function
+(@pxref{Let Function}) or with the @code{foreach} function
+(@pxref{Foreach Function}).
+
 @item
 Variables in the environment become @code{make} variables.
 @xref{Environment, ,Variables from the Environment}.
@@ -6274,10 +6281,12 @@ the Shell}.@refill
 
 Variable values in @code{make} are usually global; that is, they are the
 same regardless of where they are evaluated (unless they're reset, of
-course).  One exception to that is automatic variables
+course).  Exceptions to that are variables defined with the @code{let}
+function (@pxref{Let Function}) or the @code{foreach} function
+(@pxref{Foreach Function}, and automatic variables
 (@pxref{Automatic Variables}).
 
-The other exception is @dfn{target-specific variable values}.  This
+Another exception are @dfn{target-specific variable values}.  This
 feature allows you to define different values for the same variable,
 based on the target that @code{make} is currently building.  As with
 automatic variables, these values are only available within the context
@@ -7039,7 +7048,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.
+* Let Function::                Local variables.
 * Foreach Function::            Repeat some text with controlled variation.
 * File Function::               Write text to a file.
 * Call Function::               Expand a user-defined function.
@@ -7697,7 +7706,7 @@ the result of the expansion is the expansion of the last argument.
 @node Let Function, Foreach Function, Conditional Functions, Functions
 @section The @code{let} Function
 @findex let
-@cindex variables, lexically scoped
+@cindex variables, local
 
 The @code{let} function provides a means to limit the scope of a
 variable.  The assignment of the named variables in a @code{let}