Fix Savannah bugs # 15341, 15534, and 15533.

Rewrite large chunks of the "Commands" section of the manual to better
describe then backslash-newline handling, the SHELL variable, etc.

1 files changed, 320 insertions, 158 deletions

diff --git a/doc/make.texi b/doc/make.texi
index eba92c7..96d0f71 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -10,8 +10,8 @@
 @set RCSID $Id$
 @set EDITION 0.70
 @set VERSION 3.81
-@set UPDATED 29 Jan 2006
-@set UPDATE-MONTH Jan 2006
+@set UPDATED 5 Feb 2006
+@set UPDATE-MONTH Feb 2006
 @c ISBN provided by Lisa M. Opus Goldstein <opus@gnu.org>, 5 May 2004
 @set ISBN 1-882114-83-5
 
@@ -39,7 +39,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED},
 of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}.
 
 Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
-1998, 1999, 2000, 2002, 2003, 2004, 2005
+1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006
 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
@@ -173,8 +173,8 @@ Writing Rules
 * Directory Search::            Searching other directories for source files.
 * Phony Targets::               Using a target that is not a real file's name.
 * Force Targets::               You can use a target without commands
-                                  or prerequisites to mark other
-                                  targets as phony.
+                                  or prerequisites to mark other targets
+                                  as phony.
 * Empty Targets::               When only the date matters and the
                                   files are empty.
 * Special Targets::             Targets with special built-in meanings.
@@ -214,6 +214,7 @@ Static Pattern Rules
 
 Writing the Commands in Rules
 
+* Command Syntax::              Command syntax features and pitfalls.
 * Echoing::                     How to control when commands are echoed.
 * Execution::                   How commands are executed.
 * Parallel::                    How commands can be executed in parallel.
@@ -301,8 +302,8 @@ Using Implicit Rules
 * Implicit Variables::          How to change what predefined rules do.
 * Chained Rules::               How to use a chain of implicit rules.
 * Pattern Rules::               How to define new implicit rules.
-* Last Resort::                 How to defining commands for rules
-                                  which cannot find any.
+* Last Resort::                 How to define commands for rules which
+                                  cannot find any.
 * Suffix Rules::                The old-fashioned style of implicit rule.
 * Implicit Rule Search::        The precise algorithm for applying
                                   implicit rules.
@@ -331,15 +332,6 @@ Implicit Rule for Archive Member Targets
 
 * Archive Symbols::             How to update archive symbol directories.
 
-Makefile Conventions
-
-* Makefile Basics::             General Conventions for Makefiles
-* Utilities in Makefiles::      Utilities in Makefiles
-* Command Variables::           Variables for Specifying Commands
-* Directory Variables::         Variables for Installation Directories
-* Standard Targets::            Standard Targets for Users
-* Install Command Categories::  Three categories of commands in the `install'
-
 @end detailmenu
 @end menu
 
@@ -1852,8 +1844,8 @@ the makefile (often with a target called @samp{all}).
 * Directory Search::            Searching other directories for source files.
 * Phony Targets::               Using a target that is not a real file's name.
 * Force Targets::               You can use a target without commands
-                                  or prerequisites to mark other
-                                  targets as phony.
+                                  or prerequisites to mark other targets
+                                  as phony.
 * Empty Targets::               When only the date matters and the
                                   files are empty.
 * Special Targets::             Targets with special built-in meanings.
@@ -1937,19 +1929,23 @@ target per rule, but occasionally there is a reason to have more
 The @var{command} lines start with a tab character.  The first command may
 appear on the line after the prerequisites, with a tab character, or may
 appear on the same line, with a semicolon.  Either way, the effect is the
-same.  @xref{Commands, ,Writing the Commands in Rules}.
+same.  There are other differences in the syntax of command lines.
+@xref{Commands, ,Writing the Commands in Rules}.
 
 @cindex dollar sign (@code{$}), in rules
 @cindex @code{$}, in rules
-@cindex rule, and @code{$}
-Because dollar signs are used to start variable references, if you really
-want a dollar sign in a rule you must write two of them, @samp{$$}
-(@pxref{Using Variables, ,How to Use Variables}).  In prerequisite
-lists you must actually write @emph{four} dollar signs (@samp{$$$$}),
-due to secondary expansion (@pxref{Secondary Expansion}).
-You may split a long line by inserting a backslash
-followed by a newline, but this is not required, as @code{make} places no
-limit on the length of a line in a makefile.
+@cindex rules, and @code{$}
+Because dollar signs are used to start @code{make} variable
+references, if you really want a dollar sign in a target or
+prerequisite you must write two of them, @samp{$$} (@pxref{Using
+Variables, ,How to Use Variables}).  If you have enabled secondary
+expansion (@pxref{Secondary Expansion}) and you want a literal dollar
+sign in the prerequisites lise, you must actually write @emph{four}
+dollar signs (@samp{$$$$}).
+
+You may split a long line by inserting a backslash followed by a
+newline, but this is not required, as @code{make} places no limit on
+the length of a line in a makefile.
 
 A rule tells @code{make} two things: when the targets are out of date,
 and how to update them when necessary.
@@ -3497,28 +3493,17 @@ object file become the default goal.
 @cindex rule commands
 @cindex writing rule commands
 
-The commands of a rule consist of shell command lines to be executed one
-by one.  Each command line must start with a tab, except that the first
-command line may be attached to the target-and-prerequisites line with a
-semicolon in between.  Blank lines and lines of just comments may appear
-among the command lines; they are ignored.  (But beware, an apparently
-``blank'' line that begins with a tab is @emph{not} blank!  It is an
-empty command; @pxref{Empty Commands}.)
+The commands of a rule consist of one or more shell command lines to
+be executed, one at a time, in the order they appear.  Typically, the
+result of executing these commands is that the target of the rule is
+brought up to date.
 
 Users use many different shell programs, but commands in makefiles are
 always interpreted by @file{/bin/sh} unless the makefile specifies
 otherwise.  @xref{Execution, ,Command Execution}.
 
-@cindex comments, in commands
-@cindex commands, comments in
-@cindex @code{#} (comments), in commands
-The shell that is in use determines whether comments can be written on
-command lines, and what syntax they use.  When the shell is
-@file{/bin/sh}, a @samp{#} starts a comment that extends to the end of
-the line.  The @samp{#} does not have to be at the beginning of a line.
-Text on a line before a @samp{#} is not part of the comment.
-
 @menu
+* Command Syntax::              Command syntax features and pitfalls.
 * Echoing::                     How to control when commands are echoed.
 * Execution::                   How commands are executed.
 * Parallel::                    How commands can be executed in parallel.
@@ -3529,96 +3514,87 @@ Text on a line before a @samp{#} is not part of the comment.
 * Empty Commands::              Defining useful, do-nothing commands.
 @end menu
 
-@node Echoing, Execution, Commands, Commands
-@section Command Echoing
-@cindex echoing of commands
-@cindex silent operation
-@cindex @code{@@} (in commands)
-@cindex commands, echoing
-@cindex printing of commands
-
-Normally @code{make} prints each command line before it is executed.
-We call this @dfn{echoing} because it gives the appearance that you
-are typing the commands yourself.
-
-When a line starts with @samp{@@}, the echoing of that line is suppressed.
-The @samp{@@} is discarded before the command is passed to the shell.
-Typically you would use this for a command whose only effect is to print
-something, such as an @code{echo} command to indicate progress through
-the makefile:
-
-@example
-@@echo About to make distribution files
-@end example
+@node Command Syntax, Echoing, Commands, Commands
+@section Command Syntax
+@cindex command syntax
+@cindex syntax of commands
+
+Makefiles have the unusual property that there are really two distinct
+syntaxes in one file.  Most of the makefile uses @code{make} syntax
+(@pxref{Makefiles, ,Writing Makefiles}).  However, commands are meant to be
+interpreted by the shell and so they are written using shell syntax.
+The @code{make} program does not try to understand shell syntax: it
+performs only a very few specific translations on the content of the
+command before handing it to the shell.
+
+Each command line must start with a tab, except that the first command
+line may be attached to the target-and-prerequisites line with a
+semicolon in between.  @emph{Any} line in the makefile that begins
+with a tab and appears in a ``rule context'' (that is, after a rule
+has been started until another rule or variable definition) will be
+considered a command line for that rule.  Blank lines and lines of
+just comments may appear among the command lines; they are ignored.
+
+Some consequences of these rules include:
 
-@cindex @code{-n}
-@cindex @code{--just-print}
-@cindex @code{--dry-run}
-@cindex @code{--recon}
-When @code{make} is given the flag @samp{-n} or @samp{--just-print}
-it only echoes commands, it won't execute them.  @xref{Options Summary,
-,Summary of Options}.  In this case and only this case, even the
-commands starting with @samp{@@} are printed.  This flag is useful for
-finding out which commands @code{make} thinks are necessary without
-actually doing them.
-
-@cindex @code{-s}
-@cindex @code{--silent}
-@cindex @code{--quiet}
-@findex .SILENT
-The @samp{-s} or @samp{--silent}
-flag to @code{make} prevents all echoing, as if all commands
-started with @samp{@@}.  A rule in the makefile for the special target
-@code{.SILENT} without prerequisites has the same effect
-(@pxref{Special Targets, ,Special Built-in Target Names}).
-@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
+@itemize @bullet
+@item
+A blank line that begins with a tab is not blank: it's an empty
+command (@pxref{Empty Commands}).
 
-@node Execution, Parallel, Echoing, Commands
-@section Command Execution
-@cindex commands, execution
-@cindex execution, of commands
-@cindex shell command, execution
-@vindex SHELL @r{(command execution)}
+@cindex comments, in commands
+@cindex commands, comments in
+@cindex @code{#} (comments), in commands
+@item
+A comment in a command line is not a @code{make} comment; it will be
+passed to the shell as-is.  Whether the shell treats it as a comment
+or not depends on your shell.
 
-When it is time to execute commands to update a target, they are executed
-by making a new subshell for each line.  (In practice, @code{make} may
-take shortcuts that do not affect the results.)
+@item
+A variable definition in a ``rule context'' which is indented by a tab
+as the first character on the line, will be considered a command line,
+not a @code{make} variable definition, and passed to the shell.
 
-@cindex @code{cd} (shell command)
-@strong{Please note:} this implies that shell commands such as
-@code{cd} that set variables local to each process will not affect the
-following command lines.@footnote{On MS-DOS, the value of current
-working directory is @strong{global}, so changing it @emph{will}
-affect the following command lines on those systems.}  If you want to
-use @code{cd} to affect the next command, put them on a single line.
-Then @code{make} will consider them a single command and pass them
-both to a single shell which will execute them in sequence.  For
-example:
+@item
+A conditional expression (@code{ifdef}, @code{ifeq},
+etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule
+context'' which is indented by a tab as the first character on the
+line, will be considered a command line and be passed to the shell.
 
-@example
-foo : bar/lose
-        cd $(@@D) && gobble $(@@F) > ../$@@
-@end example
+@end itemize
 
-@noindent
-Here we use the shell AND operator (@code{&&}) so that if the
-@code{cd} command fails, the script will fail without trying to invoke
-the @code{gobble} command in the wrong directory, which could very
-easily cause problems (in this case it would certainly cause
-@file{../foo} to be truncated, at least).
+@menu
+* Splitting Lines::             Breaking long command lines for readability.
+* Variables in Commands::       Using @code{make} variables in commands.
+@end menu
 
+@node Splitting Lines, Variables in Commands, Command Syntax, Command Syntax
+@subsection Splitting Command Lines
+@cindex commands, splitting
+@cindex splitting commands
 @cindex commands, backslash (@code{\}) in
 @cindex commands, quoting newlines in
 @cindex backslash (@code{\}), in commands
 @cindex @code{\} (backslash), in commands
 @cindex quoting newline, in commands
 @cindex newline, quoting, in commands
-A shell command can be split into multiple lines of text by placing a
-backslash before each newline.  Such a sequence of lines is provided
-to the shell as a single command script.  The backslash and newline
-are preserved in the shell command.  If the first character on the
-line after a backslash-newline is a tab, the tab will @emph{not} be
-included in the shell command.  So, this makefile:
+
+One of the few ways in which @code{make} does interpret command lines
+is checking for a backslash just before the newline.  As in normal
+makefile syntax, a single command can be split into multiple lines in
+the makefile by placing a backslash before each newline.  A sequence
+of lines like this is considered a single command, and one instance of
+the shell will be invoked to run it.
+
+However, in contrast to how they are treated in other places in a
+makefile, backslash-newline pairs are @emph{not} removed from the
+command.  Both the backslash and the newline characters are preserved
+and passed to the shell.  How the backslash-newline is interpreted
+depends on your shell.  If the first character of the next line
+after the backslash-newline is a tab, then that tab (and only that
+tab) is removed.  Whitespace is never added to the command.
+
+For example, this makefile:
 
 @example
 @group
@@ -3685,9 +3661,220 @@ quotes (@code{'...'}).  This is the way the default shell (@file{/bin/sh})
 handles backslash/newline pairs.  If you specify a different shell in your
 makefiles it may treat them differently.
 
+Sometimes you want to split a long line inside of single quotes, but
+you don't want the backslash-newline to appear in the quoted content.
+This is often the case when passing scripts to languages such as Perl,
+where extraneous backslashes inside the script can change its meaning
+or even be a syntax error.  One simple way of handling this is to
+place the quoted string, or even the entire command, into a
+@code{make} variable then use the variable in the command.  In this
+situation the newline quoting rules for makefiles will be used, and
+the backslash-newline will be removed.  If we rewrite our example
+above using this method:
+
+@example
+@group
+HELLO = 'hello \
+world'
+
+all : ; @@echo $(HELLO)
+@end group
+@end example
+
+@noindent
+we will get output like this:
+
+@example
+@group
+hello world
+@end group
+@end example
+
+If you like, you can also use target-specific variables
+(@pxref{Target-specific, ,Target-specific Variable Values}) to obtain
+a tighter correspondence between the variable and the command that
+uses it.
+
+@node Variables in Commands,  , Splitting Lines, Command Syntax
+@subsection Using Variables in Commands
+@cindex variable references in commands
+@cindex commands, using variables in
+
+The other way in which @code{make} processes commands is by expanding
+any variable references in them (@pxref{Reference,Basics of Variable
+References}).  This occurs after make has finished reading all the
+makefiles and the target is determined to be out of date; so, the
+commands for targets which are not rebuilt are never expanded.
+
+Variable and function references in commands have identical syntax and
+semantics to references elsewhere in the makefile.  They also have the
+same quoting rules: if you want a dollar sign to appear in your
+command, you must double it (@samp{$$}).  For shells like the default
+shell, that use dollar signs to introduce variables, it's important to
+keep clear in your mind whether the variable you want to reference is
+a @code{make} variable (use a single dollar sign) or a shell variable
+(use two dollar signs).  For example:
+
+@example
+@group
+LIST = one two three
+all:
+        for i in $(LIST); do \
+            echo $$i; \
+        done
+@end group
+@end example
+
+@noindent
+results in the following command being passed to the shell:
+
+@example
+@group
+for i in one two three; do \
+    echo $i; \
+done
+@end group
+@end example
+
+@noindent
+which generates the expected result:
+
+@example
+@group
+one
+two
+three
+@end group
+@end example
+
+@node Echoing, Execution, Command Syntax, Commands
+@section Command Echoing
+@cindex echoing of commands
+@cindex silent operation
+@cindex @code{@@} (in commands)
+@cindex commands, echoing
+@cindex printing of commands
+
+Normally @code{make} prints each command line before it is executed.
+We call this @dfn{echoing} because it gives the appearance that you
+are typing the commands yourself.
+
+When a line starts with @samp{@@}, the echoing of that line is suppressed.
+The @samp{@@} is discarded before the command is passed to the shell.
+Typically you would use this for a command whose only effect is to print
+something, such as an @code{echo} command to indicate progress through
+the makefile:
+
+@example
+@@echo About to make distribution files
+@end example
+
+@cindex @code{-n}
+@cindex @code{--just-print}
+@cindex @code{--dry-run}
+@cindex @code{--recon}
+When @code{make} is given the flag @samp{-n} or @samp{--just-print}
+it only echoes commands, it won't execute them.  @xref{Options Summary,
+,Summary of Options}.  In this case and only this case, even the
+commands starting with @samp{@@} are printed.  This flag is useful for
+finding out which commands @code{make} thinks are necessary without
+actually doing them.
+
+@cindex @code{-s}
+@cindex @code{--silent}
+@cindex @code{--quiet}
+@findex .SILENT
+The @samp{-s} or @samp{--silent}
+flag to @code{make} prevents all echoing, as if all commands
+started with @samp{@@}.  A rule in the makefile for the special target
+@code{.SILENT} without prerequisites has the same effect
+(@pxref{Special Targets, ,Special Built-in Target Names}).
+@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
+
+@node Execution, Parallel, Echoing, Commands
+@section Command Execution
+@cindex commands, execution
+@cindex execution, of commands
+@cindex shell command, execution
+@vindex @code{SHELL} @r{(command execution)}
+
+When it is time to execute commands to update a target, they are
+executed by invoking a new subshell for each command line.  (In
+practice, @code{make} may take shortcuts that do not affect the
+results.)
+
+@cindex @code{cd} (shell command)
+@cindex shell variables, setting in commands
+@cindex commands setting shell variables
+@strong{Please note:} this implies that setting shell variables and
+invoking shell commands such as @code{cd} that set a context local to
+each process will not affect the following command lines.@footnote{On
+MS-DOS, the value of current working directory is @strong{global}, so
+changing it @emph{will} affect the following command lines on those
+systems.}  If you want to use @code{cd} to affect the next statement,
+put both statements in a single command line.  Then @code{make} will
+invoke one shell to run the entire line, and the shell will execute
+the statements in sequence.  For example:
+
+@example
+foo : bar/lose
+        cd $(@@D) && gobble $(@@F) > ../$@@
+@end example
+
+@noindent
+Here we use the shell AND operator (@code{&&}) so that if the
+@code{cd} command fails, the script will fail without trying to invoke
+the @code{gobble} command in the wrong directory, which could cause
+problems (in this case it would certainly cause @file{../foo} to be
+truncated, at least).
+
+@menu
+* Choosing the Shell::          How @code{make} chooses the shell used
+                                  to run commands.
+@end menu
+
+@node Choosing the Shell,  , Execution, Execution
+@subsection Choosing the Shell
+@cindex shell, choosing the
+@cindex @code{SHELL}, value of
+
 @vindex SHELL
 The program used as the shell is taken from the variable @code{SHELL}.
-By default, the program @file{/bin/sh} is used.
+If this variable is not set in your makefile, the program
+@file{/bin/sh} is used as the shell.
+
+@cindex environment, @code{SHELL} in
+Unlike most variables, the variable @code{SHELL} is never set from the
+environment.  This is because the @code{SHELL} environment variable is
+used to specify your personal choice of shell program for interactive
+use.  It would be very bad for personal choices like this to affect the
+functioning of makefiles.  @xref{Environment, ,Variables from the
+Environment}.
+
+Furthermore, when you do set @code{SHELL} in your makefile that value
+is @emph{not} exported in the environment to commands that @code{make}
+invokes.  Instead, the value inherited from the user's environment, if
+any, is exported.  You can override this behavior by explicitly
+exporting @code{SHELL} (@pxref{Variables/Recursion, ,Communicating
+Variables to a Sub-@code{make}}), forcing it to be passed in the
+environment to commands.
+
+@vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})}
+However, on MS-DOS and MS-Windows the value of @code{SHELL} in the
+environment @strong{is} used, since on those systems most users do not
+set this variable, and therefore it is most likely set specifically to
+be used by @code{make}.  On MS-DOS, if the setting of @code{SHELL} is
+not suitable for @code{make}, you can set the variable
+@code{MAKESHELL} to the shell that @code{make} should use; if set it
+will be used as the shell instead of the value of @code{SHELL}.
+
+@subsubheading Choosing a Shell in DOS and Windows
+@cindex shell, in DOS and Windows
+@cindex DOS, choosing a shell in
+@cindex Windows, choosing a shell in
+
+Choosing a shell in MS-DOS and MS-Windows is much more complex than on
+other systems.
 
 @vindex COMSPEC
 On MS-DOS, if @code{SHELL} is not set, the value of the variable
@@ -3741,25 +3928,10 @@ environment or command line, you are expected to set it to the full
 pathname of the shell, exactly as things are on Unix.
 
 The effect of the above DOS-specific processing is that a Makefile that
-says @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work
+contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work
 on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some
 directory along your @code{PATH}.
 
-@cindex environment, @code{SHELL} in
-@vindex MAKESHELL @r{(MS-DOS alternative to @code{SHELL})}
-Unlike most variables, the variable @code{SHELL} is never set from the
-environment.  This is because the @code{SHELL} environment variable is
-used to specify your personal choice of shell program for interactive
-use.  It would be very bad for personal choices like this to affect the
-functioning of makefiles.  @xref{Environment, ,Variables from the
-Environment}.  However, on MS-DOS and MS-Windows the value of
-@code{SHELL} in the environment @strong{is} used, since on those systems
-most users do not set this variable, and therefore it is most likely set
-specifically to be used by @code{make}.  On MS-DOS, if the setting of
-@code{SHELL} is not suitable for @code{make}, you can set the variable
-@code{MAKESHELL} to the shell that @code{make} should use; this will
-override the value of @code{SHELL}.
-
 @node Parallel, Errors, Execution, Commands
 @section Parallel Execution
 @cindex commands, execution in parallel
@@ -4128,7 +4300,7 @@ The value of the @code{make} variable @code{SHELL} is not exported.
 Instead, the value of the @code{SHELL} variable from the invoking
 environment is passed to the sub-@code{make}.  You can force
 @code{make} to export its value for @code{SHELL} by using the
-@code{export} directive, described below.
+@code{export} directive, described below.  @xref{Choosing the Shell}.
 
 The special variable @code{MAKEFLAGS} is always exported (unless you
 unexport it).  @code{MAKEFILES} is exported if you set it to anything.
@@ -5564,22 +5736,12 @@ different results from the same makefile.  This is against the whole
 purpose of most makefiles.
 
 @cindex SHELL, import from environment
-Such problems would be especially likely with the variable @code{SHELL},
-which is normally present in the environment to specify the user's choice
-of interactive shell.  It would be very undesirable for this choice to
-affect @code{make}.  So @code{make} ignores the environment value of
-@code{SHELL} (except on MS-DOS and MS-Windows, where @code{SHELL} is
-usually not set.  @xref{Execution, ,Special handling of SHELL on
-MS-DOS}.)@refill
-
-@cindex SHELL, export to environment
-The @code{SHELL} variable is special in another way: just as the value
-of the @code{make} variable @code{SHELL} is not taken from the
-environment, so also it is not placed into the environment of commands
-that @code{make} invokes.  Instead, the value of @code{SHELL} from the
-invoking environment is provided to the command.  You can use
-@code{export SHELL} to force the value of the @code{make} variable
-@code{SHELL} to be placed in the environment of commands.
+Such problems would be especially likely with the variable
+@code{SHELL}, which is normally present in the environment to specify
+the user's choice of interactive shell.  It would be very undesirable
+for this choice to affect @code{make}; so, @code{make} handles the
+@code{SHELL} environment variable in a special way; see @ref{Choosing
+the Shell}.@refill
 
 @node Target-specific, Pattern-specific, Environment, Using Variables
 @section Target-specific Variable Values
@@ -8067,7 +8229,7 @@ retained for compatibility.
 * Chained Rules::               How to use a chain of implicit rules.
 * Pattern Rules::               How to define new implicit rules.
 * Last Resort::                 How to define commands for rules which
-                                cannot find any.
+                                  cannot find any.
 * Suffix Rules::                The old-fashioned style of implicit rule.
 * Implicit Rule Search::        The precise algorithm for applying
                                   implicit rules.
@@ -8491,7 +8653,7 @@ with spaces.
 
 The following tables describe of some of the more commonly-used predefined
 variables.  This list is not exhaustive, and the default values shown here may
-not be what is selected by @code{make} for your environment.  To see the
+not be what are selected by @code{make} for your environment.  To see the
 complete list of predefined variables for your instance of GNU @code{make} you
 can run @samp{make -p} in a directory with no makefiles.
 
@@ -10423,7 +10585,7 @@ The name of the system default command interpreter, usually @file{/bin/sh}.
 You can set @code{SHELL} in the makefile to change the shell used to run
 commands.  @xref{Execution, ,Command Execution}.  The @code{SHELL}
 variable is handled specially when importing from and exporting to the
-environment.  @xref{Environment, ,Using Variable from the Environment}.
+environment.  @xref{Choosing the Shell}.
 
 @item MAKESHELL