Various changes getting ready for the release of 3.81.

- Updates to make.texi and make.1 and other documentation
- Some VMS patches
- Fix minor bugs reported on the mailing list and from Debian.

1 files changed, 124 insertions, 72 deletions

diff --git a/doc/make.texi b/doc/make.texi
index ed864f9..b0de845 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 07 May 2005
-@set UPDATE-MONTH May 2005
+@set UPDATED 28 Dec 2005
+@set UPDATE-MONTH Dec 2005
 @c ISBN provided by Lisa M. Opus Goldstein <opus@gnu.org>, 5 May 2004
 @set ISBN 1-882114-83-5
 
@@ -1290,7 +1290,7 @@ Sets the default goal to be used if no targets were specified on the
 command line (@pxref{Goals, , Arguments to Specify the Goals}).  The
 @code{.DEFAULT_GOAL} variable allows you to discover the current
 default goal, restart the default goal selection algorithm by clearing
-its value, or to explicitly set the default goal. The following
+its value, or to explicitly set the default goal.  The following
 example illustrates these cases:
 
 @example
@@ -1738,7 +1738,7 @@ when the target is an archive member, the target member name.  The
 rule for this target.  @code{$$^} and @code{$$+} evaluate to the list
 of all prerequisites of rules @emph{that have already appeared} for
 the same target (@code{$$+} with repetitions and @code{$$^}
-without). The following example will help illustrate these behaviors:
+without).  The following example will help illustrate these behaviors:
 
 @example
 .SECONDEXPANSION:
@@ -1750,12 +1750,12 @@ foo: foo.2 bar.2 $$< $$^ $$+    # line #2
 foo: foo.3 bar.3 $$< $$^ $$+    # line #3
 @end example
 
-For the first line, all three variables (@code{$$<}, @code{$$^}, and
-@code{$$+}) expand to the empty string. For the second line, they will
-have values @code{foo.1}, @code{foo.1 bar.1}, and @code{foo.1 bar.1}
-respectively. For the third they will have values @code{foo.1},
-@code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1 foo.2 bar.2}
-respectively.
+In the first prerequisite list, all three variables (@code{$$<},
+@code{$$^}, and @code{$$+}) expand to the empty string.  In the
+second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and
+@code{foo.1 bar.1} respectively.  In the third they will have values
+@code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1
+foo.2 bar.2} respectively.
 
 Rules undergo secondary expansion in makefile order, except that
 the rule with the command script is always evaluated last.
@@ -2680,8 +2680,8 @@ build the rest of the directories even when one fails.  This can be
 overcome by adding shell commands to note the error and exit, but then
 it will do so even if @code{make} is invoked with the @code{-k} option,
 which is unfortunate.  Second, and perhaps more importantly, you cannot
-take advantage of the parallel build capabilities of make using this
-method, since there is only one rule.
+take advantage of @code{make}'s ability to build targets in parallel
+(@pxref{Parallel, ,Parallel Execution}), since there is only one rule.
 
 By declaring the subdirectories as phony targets (you must do this as
 the subdirectory obviously always exists; otherwise it won't be built)
@@ -2907,7 +2907,7 @@ intermediate).
 @findex .SECONDEXPANSION
 @item .SECONDEXPANSION
 
-If @code{.SECONDEXPANSION} is mentioned as a target anwyeren in the
+If @code{.SECONDEXPANSION} is mentioned as a target anywhere in the
 makefile, then all prerequisite lists defined @emph{after} it appears
 will be expanded a second time after all makefiles have been read in.
 @xref{Secondary Expansion, ,Secondary Expansion}.
@@ -3424,7 +3424,7 @@ called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
 @smallexample
 @group
 %.d: %.c
-        @set -e; rm -f $@@; \
+        @@set -e; rm -f $@@; \
          $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \
          sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \
          rm -f $@@.$$$$
@@ -3585,21 +3585,28 @@ by making a new subshell for each line.  (In practice, @code{make} may
 take shortcuts that do not affect the results.)
 
 @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 the two on a single line with a
-semicolon between them.  Then @code{make} will consider them a single
-command and pass them, together, to a shell which will execute them in
-sequence.  For example:
+@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:
 
 @example
 foo : bar/lose
-        cd bar; gobble lose > ../foo
+        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 very
+easily cause problems (in this case it would certainly cause
+@file{../foo} to be truncated, at least).
+
 @cindex commands, backslash (@code{\}) in
 @cindex commands, quoting newlines in
 @cindex backslash (@code{\}), in commands
@@ -3620,15 +3627,22 @@ all :
 space
         @@echo no\
         space
+        @@echo one \
+        space
+        @@echo one\
+         space
 @end group
 @end example
 
-consists of two separate shell commands where the output is:
+@noindent
+consists of four separate shell commands where the output is:
 
 @example
 @group
 nospace
 nospace
+one space
+one space
 @end group
 @end example
 
@@ -3642,6 +3656,7 @@ all : ; @@echo 'hello \
 @end group
 @end example
 
+@noindent
 will run one shell with a command script of:
 
 @example
@@ -3652,6 +3667,7 @@ world' ; echo "hello \
 @end group
 @end example
 
+@noindent
 which, according to shell quoting rules, will yield the following output:
 
 @example
@@ -3662,6 +3678,13 @@ hello     world
 @end group
 @end example
 
+@noindent
+Notice how the backslash/newline pair was removed inside the string quoted
+with double quotes (@code{"..."}), but not from the string quoted with single
+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.
+
 @vindex SHELL
 The program used as the shell is taken from the variable @code{SHELL}.
 By default, the program @file{/bin/sh} is used.
@@ -3719,7 +3742,7 @@ 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
-on MS-DOS unaltered if you have e.g. @file{sh.exe} installed in some
+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
@@ -5287,7 +5310,7 @@ definition of the variable.  If you defined it first with @samp{:=},
 making it a simply-expanded variable, @samp{+=} adds to that
 simply-expanded definition, and expands the new text before appending it
 to the old value just as @samp{:=} does
-(@pxref{Setting, ,Setting Variables} for a full explanation of @samp{:=}).
+(see @ref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}).
 In fact,
 
 @example
@@ -5528,7 +5551,7 @@ and therefore are not affected by the value in the environment.)
 
 When @code{make} runs a command script, variables defined in the
 makefile are placed into the environment of that command.  This allows
-you to pass values to sub-@code{make} invocations. (@pxref{Recursion,
+you to pass values to sub-@code{make} invocations (@pxref{Recursion,
 ,Recursive Use of @code{make}}).  By default, only variables that came
 from the environment or the command line are passed to recursive
 invocations.  You can use the @code{export} directive to pass other
@@ -5605,7 +5628,7 @@ conditional (@samp{?=}).  All variables that appear within the
 target: thus, any previously-defined target-specific variable values
 will be in effect.  Note that this variable is actually distinct from
 any ``global'' value: the two variables do not have to have the same
-flavor (recursive vs. static).
+flavor (recursive vs.@: static).
 
 Target-specific variables have the same priority as any other makefile
 variable.  Variables provided on the command-line (and in the
@@ -5616,7 +5639,7 @@ variable value to be preferred.
 There is one more special feature of target-specific variables: when
 you define a target-specific variable that variable value is also in
 effect for all prerequisites of this target, and all their
-prerequisites, etc. (unless those prerequisites override that variable
+prerequisites, etc.@: (unless those prerequisites override that variable
 with their own target-specific variable value).  So, for example, a
 statement like this:
 
@@ -6596,8 +6619,8 @@ that match the pattern.
 @cindex file name, realpath of
 For each file name in @var{names} return the canonical absolute name.
 A canonical name does not contain any @code{.} or @code{..} components,
-nor any repeated path separators (@code{/}) or symlinks. In case of a
-failure the empty string is returned. Consult the @code{realpath(3)}
+nor any repeated path separators (@code{/}) or symlinks.  In case of a
+failure the empty string is returned.  Consult the @code{realpath(3)}
 documentation for a list of possible failure causes.
 
 @item $(abspath @var{names}@dots{})
@@ -6606,9 +6629,9 @@ documentation for a list of possible failure causes.
 @cindex file name, abspath of
 For each file name in @var{names} return an absolute name that does
 not contain any @code{.} or @code{..} components, nor any repeated path
-separators (@code{/}). Note that in contrast to @code{realpath}
+separators (@code{/}).  Note that, in contrast to @code{realpath}
 function, @code{abspath} does not resolve symlinks and does not require
-the file names to refer to an existing file or directory. Use the
+the file names to refer to an existing file or directory.  Use the
 @code{wildcard} function to test for existence.
 @end table
 
@@ -6804,7 +6827,7 @@ LS := $(call pathsearch,ls)
 Now the variable LS contains @code{/bin/ls} or similar.
 
 The @code{call} function can be nested.  Each recursive invocation gets
-its own local values for @code{$(1)}, etc. that mask the values of
+its own local values for @code{$(1)}, etc.@: that mask the values of
 higher-level @code{call}.  For example, here is an implementation of a
 @dfn{map} function:
 
@@ -7058,9 +7081,9 @@ Here the redefinition takes place if @samp{$(origin bletch)} returns either
 
 The @code{flavor} function is unlike most other functions (and like
 @code{origin} function) in that it does not operate on the values of
-variables; it tells you something @emph{about} a variable. Specifically,
-it tells you the flavor of a variable
-(@pxref{Flavors, ,The Two Flavors of Variables}).
+variables; it tells you something @emph{about} a variable.
+Specifically, it tells you the flavor of a variable (@pxref{Flavors,
+,The Two Flavors of Variables}).
 
 The syntax of the @code{flavor} function is:
 
@@ -7117,7 +7140,7 @@ function calls are expanded (@pxref{Reading Makefiles, , How
 @code{make} Reads a Makefile}).  Because this function involves
 spawning a new shell, you should carefully consider the performance
 implications of using the @code{shell} function within recursively
-expanded variables vs. simply expanded variables (@pxref{Flavors, ,The
+expanded variables vs.@: simply expanded variables (@pxref{Flavors, ,The
 Two Flavors of Variables}).
 
 Here are some examples of the use of the @code{shell} function:
@@ -7217,6 +7240,7 @@ find out which files are out of date without changing them.
 By giving arguments when you run @code{make}, you can do any of these
 things and many others.
 
+@cindex exit status of make
 The exit status of @code{make} is always one of three values:
 @table @code
 @item 0
@@ -8139,13 +8163,19 @@ available unless the makefile explicitly overrides or cancels them.
 canceling or overriding an implicit rule.  The @samp{-r} or
 @samp{--no-builtin-rules} option cancels all predefined rules.
 
+This manual only documents the default rules available on POSIX-based
+operating systems.  Other operating systems, such as VMS, Windows,
+OS/2, etc. may have different sets of default rules.  To see the full
+list of default rules and variables available in your version of GNU
+@code{make}, run @samp{make -p} in a directory with no makefile.
+
 Not all of these rules will always be defined, even when the @samp{-r}
 option is not given.  Many of the predefined implicit rules are
 implemented in @code{make} as suffix rules, so which ones will be
 defined depends on the @dfn{suffix list} (the list of prerequisites of
 the special target @code{.SUFFIXES}).  The default suffix list is:
 @code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
-@code{.C}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
+@code{.C}, @code{.cpp}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
 @code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def},
 @code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo},
 @code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web},
@@ -8170,12 +8200,13 @@ a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
 @item Compiling C++ programs
 @cindex C++, rule to compile
 @pindex g++
-@pindex .C
 @pindex .cc
-@file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
-@file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS)
-$(CXXFLAGS)}.  We encourage you to use the suffix @samp{.cc} for C++
-source files instead of @samp{.C}.@refill
+@pindex .cpp
+@pindex .C
+@file{@var{n}.o} is made automatically from @file{@var{n}.cc},
+@file{@var{n}.cpp}, or @file{@var{n}.C} with a command of the form
+@samp{$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)}.  We encourage you to use the
+suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill
 
 @item Compiling Pascal programs
 @cindex Pascal, rule to compile
@@ -8436,11 +8467,11 @@ the value @w{@samp{; mv $*.o $@@}}.
 @cindex flags for compilers
 
 The commands in built-in implicit rules make liberal use of certain
-predefined variables.  You can alter these variables in the makefile,
-with arguments to @code{make}, or in the environment to alter how the
-implicit rules work without redefining the rules themselves.  You can
-cancel all variables used by implicit rules with the @samp{-R} or
-@samp{--no-builtin-variables} option.
+predefined variables.  You can alter the values of these variables in
+the makefile, with arguments to @code{make}, or in the environment to
+alter how the implicit rules work without redefining the rules
+themselves.  You can cancel all variables used by implicit rules with
+the @samp{-R} or @samp{--no-builtin-variables} option.
 
 For example, the command used to compile a C source file actually says
 @samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}.  The default values of the variables
@@ -8459,7 +8490,15 @@ some command arguments, but it must start with an actual executable program
 name.)  If a variable value contains more than one argument, separate them
 with spaces.
 
-Here is a table of variables used as names of programs in built-in rules:
+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
+complete list of predefined variables for your instance of GNU @code{make} you
+can run @samp{make -p} in a directory with no makefiles.
+
+Here is a table of some of the more common variables used as names of
+programs in built-in rules:
+makefiles.
 
 @table @code
 @item AR
@@ -8469,7 +8508,7 @@ Archive-maintaining program; default @samp{ar}.
 
 @item AS
 @vindex AS
-Program for doing assembly; default @samp{as}.
+Program for compiling assembly files; default @samp{as}.
 @pindex as
 
 @item CC
@@ -8477,6 +8516,11 @@ Program for doing assembly; default @samp{as}.
 Program for compiling C programs; default @samp{cc}.
 @pindex cc
 
+@item CO
+@vindex CO
+Program for checking out files from RCS; default @samp{co}.
+@pindex cc
+
 @item CXX
 @vindex CXX
 Program for compiling C++ programs; default @samp{g++}.
@@ -8505,24 +8549,28 @@ Program for extracting a file from SCCS; default @samp{get}.
 
 @item LEX
 @vindex LEX
-Program to use to turn Lex grammars into C programs or Ratfor programs;
-default @samp{lex}.
+Program to use to turn Lex grammars into source code; default @samp{lex}.
 @pindex lex
 
-@item PC
-@vindex PC
-Program for compiling Pascal programs; default @samp{pc}.
-@pindex pc
-
 @item YACC
 @vindex YACC
-Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
+Program to use to turn Yacc grammars into source code; default @samp{yacc}.
 @pindex yacc
 
-@item YACCR
-@vindex YACCR
-Program to use to turn Yacc grammars into Ratfor
-programs; default @samp{yacc -r}.
+@item LINT
+@vindex LINT
+Program to use to run lint on source code; default @samp{lint}.
+@pindex lint
+
+@item M2C
+@vindex M2C
+Program to use to compile Modula-2 source code; default @samp{m2c}.
+@pindex m2c
+
+@item PC
+@vindex PC
+Program for compiling Pascal programs; default @samp{pc}.
+@pindex pc
 
 @item MAKEINFO
 @vindex MAKEINFO
@@ -8609,13 +8657,17 @@ Extra flags to give to the SCCS @code{get} program.
 
 @item LDFLAGS
 @vindex LDFLAGS
-Extra flags to give to compilers when they are
-supposed to invoke the linker, @samp{ld}.
+Extra flags to give to compilers when they are supposed to invoke the linker,
+@samp{ld}.
 
 @item LFLAGS
 @vindex LFLAGS
 Extra flags to give to Lex.
 
+@item YFLAGS
+@vindex YFLAGS
+Extra flags to give to Yacc.
+
 @item PFLAGS
 @vindex PFLAGS
 Extra flags to give to the Pascal compiler.
@@ -8624,9 +8676,9 @@ Extra flags to give to the Pascal compiler.
 @vindex RFLAGS
 Extra flags to give to the Fortran compiler for Ratfor programs.
 
-@item YFLAGS
-@vindex YFLAGS
-Extra flags to give to Yacc.
+@item LINTFLAGS
+@vindex LINTFLAGS
+Extra flags to give to lint.
 @end table
 
 @node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules
@@ -9119,7 +9171,7 @@ before it is compared with the target prefix and suffix.  After the
 comparison of the file name to the target pattern, the directory
 names, along with the slash that ends them, are added on to the
 prerequisite file names generated from the pattern rule's prerequisite
-patterns and the file name. The directories are ignored only for the
+patterns and the file name.  The directories are ignored only for the
 purpose of finding an implicit rule to use, not in the application of
 that rule.  Thus, @samp{e%t} matches the file name @file{src/eat},
 with @samp{src/a} as the stem.  When prerequisites are turned into file
@@ -10276,7 +10328,7 @@ and concatenate the results.@*
 @item $(call @var{var},@var{param},@dots{})
 
 Evaluate the variable @var{var} replacing any references to @code{$(1)},
-@code{$(2)} with the first, second, etc. @var{param} values.@*
+@code{$(2)} with the first, second, etc.@: @var{param} values.@*
 @xref{Call Function, ,The @code{call} Function}.
 
 @item $(eval @var{text})
@@ -10376,7 +10428,7 @@ environment.  @xref{Environment, ,Using Variable from the Environment}.
 @item MAKESHELL
 
 On MS-DOS only, the name of the command interpreter that is to be used
-by @code{make}. This value takes precedence over the value of
+by @code{make}.  This value takes precedence over the value of
 @code{SHELL}.  @xref{Execution, ,MAKESHELL variable}.
 
 @item MAKE