Formerly make.texinfo.~58~

1 files changed, 330 insertions, 183 deletions

diff --git a/make.texinfo b/make.texinfo
index a2c7173..80a14ba 100644
--- a/make.texinfo
+++ b/make.texinfo
@@ -15,8 +15,16 @@
 
 @c Combine the variable and function indices:
 @synindex vr fn
-@c Combine the program and function indices:
-@synindex pg fn
+@c Combine the program and concept indices:
+@synindex pg cp
+
+@tex
+% trying for a two-level index
+\def\doindex#1{\message{FNORD!!!}\edef\indexname{#1}\parsearg\singleindexer}
+\def\singleindexer #1{\message{frobozzing :{#1}:}\message{}\frobozz{#1}}
+\def\frobozz[#1,#2]{\message{frobozzed :{#1}:{#2}:}\message{}\dosubind{\indexname}{#1}{#2}}
+
+@end tex
 
 @ifinfo
 This file documents the GNU Make utility, which determines
@@ -419,7 +427,7 @@ Please include the version number of @code{make} you are using.  You can
 get this information with the command @samp{make --version -f /dev/null}.
 Be sure also to include the type of machine and operating system you are
 using.  If possible, include the contents of the file @file{config.h}
-that is generated by the configuration process.@c !!! make this real
+that is generated by the configuration process.
 
 Non-bug suggestions are always welcome as well.  If you have questions
 about things that are unclear in the documentation or are just obscure
@@ -572,6 +580,11 @@ clean :
 @noindent
 We split each long line into two lines using a backslash-newline; this is
 like using one long line, but is easier to read.
+@cindex continuation lines
+@cindex @code{\} (backslash), for continuation lines
+@cindex backslash (@code{\}), for continuation lines
+@cindex quoting newline, in makefile
+@cindex newline, quoting, in makefile
 
 To use this makefile to create the executable file called @file{edit},
 type:
@@ -622,7 +635,7 @@ Targets}, for information about this kind of target.  @xref{Errors, ,
 Errors in Commands}, to see how to cause @code{make} to ignore errors
 from @code{rm}.
 @cindex @code{clean} target
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
 
 @node How Make Works, Variables Simplify, Simple Makefile, Introduction
 @comment  node-name,  next,  previous,  up
@@ -924,16 +937,16 @@ and @dfn{comments}.  Rules, variables, and directives are described at
 length in later chapters.@refill
 
 @itemize @bullet
-@cindex rule, explicit (definition of)
-@cindex explicit rule (definition of)
+@cindex rule, explicit, definition of
+@cindex explicit rule, definition of
 @item
 An @dfn{explicit rule} says when and how to remake one or more files,
 called the rule's targets.  It lists the other files that the targets
 @dfn{depend on}, and may also give commands to use to create or update
 the targets.  @xref{Rules, ,Writing Rules}.
 
-@cindex rule, implicit (definition of)
-@cindex implicit rule (definition of)
+@cindex rule, implicit, definition of
+@cindex implicit rule, definition of
 @item
 An @dfn{implicit rule} says when and how to remake a class of files
 based on their names.  It describes how a target may depend on a file
@@ -980,18 +993,18 @@ perhaps spaces before it) is effectively blank, and is ignored.@refill
 
 @node Makefile Names, Include, Makefile Contents, Makefiles
 @section What Name to Give Your Makefile
-@cindex makefile names
-@cindex names of makefiles
-@cindex default makefile names
-@cindex file names of makefiles
+@cindex makefile name
+@cindex name of makefile
+@cindex default makefile name
+@cindex file name of makefile
 
 @c following paragraph rewritten to avoid overfull hbox
 By default, when @code{make} looks for the makefile, it tries the
 following names, in order: @file{GNUmakefile}, @file{makefile}
 and @file{Makefile}.@refill
-@pindex Makefile
-@pindex GNUmakefile
-@pindex makefile
+@findex Makefile
+@findex GNUmakefile
+@findex makefile
 
 @cindex @code{README}
 Normally you should call your makefile either @file{makefile} or
@@ -1024,12 +1037,12 @@ specify @samp{-f} or @samp{--file}.@refill
 @cindex specifying makefile name
 @cindex makefile name, how to specify
 @cindex name of makefile, how to specify
-@cindex file names of makefiles, how to specify
+@cindex file name of makefile, how to specify
 
 @node Include, MAKEFILES Variable, Makefile Names, Makefiles
 @section Including Other Makefiles
 @cindex including other makefiles
-@cindex makefiles, including
+@cindex makefile, including
 
 @findex include
 The @code{include} directive tells @code{make} to suspend reading the
@@ -1044,7 +1057,7 @@ include @var{filenames}@dots{}
 @var{filenames} can contain shell file name patterns.
 @cindex shell file name pattern (in @code{include})
 @cindex shell wildcards (in @code{include})
-@cindex wildcards (in @code{include})
+@cindex wildcard, in @code{include}
 
 Extra spaces are allowed and ignored at the beginning of the line, but
 a tab is not allowed.  (If the line begins with a tab, it will be
@@ -1089,24 +1102,27 @@ makefile as has been traditionally done with other versions of
 @cindex dependencies, automatic generation
 
 @cindex @code{-I}
+@cindex @code{--include-dir}
 If the specified name does not start with a slash, and the file is not
 found in the current directory, several other directories are searched.
-First, any directories you have specified with the @samp{-I} option are
-searched 
-(@pxref{Options Summary, ,Summary of Options}).  
-Then the following directories (if they
-exist) are searched, in this order: @file{/usr/gnu/include},
-@file{/usr/local/include}, @file{/usr/include}.
-If an included makefile cannot be found in any of these directories, a
-warning message is generated, but it is not a fatal error; processing
-of the makefile containing the @code{include} continues.@refill
-@pindex /usr/gnu/include
-@pindex /usr/local/include
-@pindex /usr/include
+First, any directories you have specified with the @samp{-I} or
+@samp{--include-dir} option are searched
+(@pxref{Options Summary, ,Summary of Options}).
+Then the following directories (if they exist)
+are searched, in this order: 
+@file{@var{prefix}/include} (normally @file{/usr/local/include})
+@file{/usr/gnu/include},
+@file{/usr/local/include}, @file{/usr/include}.  If an included makefile
+cannot be found in any of these directories, a warning message is
+generated, but it is not a fatal error; processing of the makefile
+containing the @code{include} continues.@refill
+@findex /usr/gnu/include
+@findex /usr/local/include
+@findex /usr/include
 
 @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
 @section The Variable @code{MAKEFILES}
-@cindex makefiles (@code{MAKEFILES} variable)
+@cindex makefile, and @code{MAKEFILES} variable
 @cindex including (@code{MAKEFILES} variable)
 
 @vindex MAKEFILES
@@ -1139,7 +1155,7 @@ in the makefiles.  @xref{Include, , Including Other Makefiles}.
 
 @cindex updating makefiles
 @cindex remaking makefiles
-@cindex makefiles, remaking of
+@cindex makefile, remaking of
 Sometimes makefiles can be remade from other files, such as RCS or SCCS
 files.  If a makefile can be remade from other files, you probably want
 @code{make} to get an up-to-date version of the makefile to read in.
@@ -1166,10 +1182,10 @@ else.  So, to avoid this, @code{make} will @strong{not} attempt to
 remake makefiles which are specified as double-colon targets but have no
 dependencies.@refill
 
-If you do not specify any makefiles to be read with @samp{-f} options,
-@code{make} will try the default makefile names;
-@pxref{Makefile Names, ,What Name to Give Your Makefile}.
-Unlike makefiles explicitly requested with @samp{-f} options,
+If you do not specify any makefiles to be read with @samp{-f} or
+@samp{--file} options, @code{make} will try the default makefile names;
+@pxref{Makefile Names, ,What Name to Give Your Makefile}.  Unlike
+makefiles explicitly requested with @samp{-f} or @samp{--file} options,
 @code{make} is not certain that these makefiles should exist.  However,
 if a default makefile does not exist but can be created by running
 @code{make} rules, you probably want the rules to be run so that the
@@ -1211,7 +1227,7 @@ specified by the existing contents of @file{mfile}.
 @section Overriding Part of Another Makefile
 
 @cindex overriding makefiles
-@cindex makefiles, overriding
+@cindex makefile, overriding
 Sometimes it is useful to have a makefile that is mostly just like
 another makefile.  You can often use the @samp{include} directive to
 include one in the other, and add more targets or variable definitions.
@@ -1368,9 +1384,9 @@ appear on the line after the dependencies, 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}.
 
-@cindex dollar signs in rules
-@cindex @code{$} in rules
-@cindex rules, and @code{$}
+@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}).  
@@ -1403,9 +1419,9 @@ executed by the shell (normally @samp{sh}), but with some extra features
 @cindex file name with wildcards
 @cindex globbing (wildcards)
 
-@cindex * (wildcard character)
-@cindex ? (wildcard character)
-@cindex [@dots{}] (wildcard characters)
+@cindex @code{*} (wildcard character)
+@cindex @code{?} (wildcard character)
+@cindex @code{[@dots{}]} (wildcard characters)
 A single file name can specify many files using @dfn{wildcard characters}.
 The wildcard characters in @code{make} are @samp{*}, @samp{?} and
 @samp{[@dots{}]}, the same as in the Bourne shell.  For example, @file{*.c}
@@ -1451,7 +1467,7 @@ clean:
         rm -f *.o
 @end group
 @end example
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
 
 Wildcards are also useful in the dependencies of a rule.  With the
 following rule in the makefile, @samp{make print} will print all the
@@ -1464,8 +1480,8 @@ print: *.c
 @end example
 
 @cindex @code{print} target
-@pindex lpr @r{(shell command)}
-@pindex touch @r{(shell command)}
+@cindex @code{lpr} (shell command)
+@cindex @code{touch} (shell command)
 @noindent
 This rule uses @file{print} as an empty target file; see @ref{Empty
 Targets, ,Empty Target Files to Record Events}.  (The automatic variable
@@ -1589,6 +1605,7 @@ there is no need to write explicit rules for compiling the files.
 @vindex VPATH
 @findex vpath
 @cindex vpath 
+@c !!! s/search path/search path for dependencies (@code{VPATH})/
 @cindex search path for dependencies (@code{VPATH})
 @cindex directory search (@code{VPATH})
 
@@ -1681,36 +1698,6 @@ The search path, @var{directories}, is a colon-separated list of
 directories to be searched, just like the search path used in the
 @code{VPATH} variable.
 
-@code{make} handles multiple @code{vpath} directives in the order in
-which they appear in the makefile; multiple directives with the same
-pattern are independent of each other.
-
-@need 750
-Thus, 
-
-@example
-@group
-vpath %.c foo
-vpath %   blish
-vpath %.c bar
-@end group
-@end example
-
-@noindent
-will look for a file ending in @samp{.c} in @file{foo}, then
-@file{blish}, then @file{bar}, while
-
-@example
-@group
-vpath %.c foo:bar
-vpath %   blish
-@end group
-@end example
-
-@noindent
-will look for a file ending in @samp{.c} in @file{foo}, then
-@file{bar}, then @file{blish}.
-
 @item vpath @var{pattern}
 Clear out the search path associated with @var{pattern}.
 
@@ -1728,6 +1715,11 @@ Redefining Pattern Rules}).  For example, @code{%.h} matches files that
 end in @code{.h}.  (If there is no @samp{%}, the pattern must match the
 dependency exactly, which is not useful very often.)
 
+@cindex @code{%}, quoting in @code{vpath}
+@cindex @code{%}, quoting with @code{\} (backslash)
+@cindex @code{\} (backslash), to quote @code{%}
+@cindex backslash (@code{\}), to quote @code{%}
+@cindex quoting @code{%}, in @code{vpath}
 @samp{%} characters in a @code{vpath} directive's pattern can be quoted
 with preceding backslashes (@samp{\}).  Backslashes that would otherwise
 quote @samp{%} characters can be quoted with more backslashes.
@@ -1753,12 +1745,41 @@ directory.
 
 If several @code{vpath} patterns match the dependency file's name, then
 @code{make} processes each matching @code{vpath} directive one by one,
-searching all the directories mentioned in each directive.  The @code{vpath}
-directives are processed in the order in which they appear in the makefiles.
+searching all the directories mentioned in each directive.  @code{make}
+handles multiple @code{vpath} directives in the order in which they
+appear in the makefile; multiple directives with the same pattern are
+independent of each other.
+
+@need 750
+Thus, 
+
+@example
+@group
+vpath %.c foo
+vpath %   blish
+vpath %.c bar
+@end group
+@end example
+
+@noindent
+will look for a file ending in @samp{.c} in @file{foo}, then
+@file{blish}, then @file{bar}, while
+
+@example
+@group
+vpath %.c foo:bar
+vpath %   blish
+@end group
+@end example
+
+@noindent
+will look for a file ending in @samp{.c} in @file{foo}, then
+@file{bar}, then @file{blish}.
 
 @node Commands/Search, Implicit/Search, Selective Search, Directory Search
 @subsection Writing Shell Commands with Directory Search
-@cindex shell commands, and directory search
+@cindex shell command, and directory search
+@c !!! s/directory search/& (VPATH)/
 @cindex directory search, and shell commands
 
 When a dependency is found in another directory through directory search,
@@ -1780,7 +1801,7 @@ foo.o : foo.c
 
 @noindent
 (The variable @code{CFLAGS} exists so you can specify flags for C
-compilation by implicit rule; we use it here for consistency so it will
+compilation by implicit rules; we use it here for consistency so it will
 affect all C compilations uniformly;
 @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
 
@@ -1799,8 +1820,10 @@ foo.o : foo.c defs.h hack.h
 @cindex @code{VPATH}, and implicit rules
 @cindex directory search, and implicit rules
 @cindex search path, and implicit rules
-@cindex implicit rules, and directory search
-@cindex implicit rules, and @code{VPATH}
+@cindex implicit rule, and directory search
+@cindex implicit rule, and @code{VPATH}
+@cindex rule, implicit, and directory search
+@cindex rule, implicit, and @code{VPATH}
 
 The search through the directories specified in @code{VPATH} or with
 @code{vpath} happens also during consideration of implicit rules
@@ -1835,9 +1858,10 @@ file, and the @emph{file name} of the library looks like
 
 When a dependency's name has the form @samp{-l@var{name}}, @code{make}
 handles it specially by searching for the file @file{lib@var{name}.a} in
-the directories @file{/lib}, @file{/usr/lib}, and @file{/usr/local/lib},
-and then using matching @code{vpath} search paths and the @code{VPATH}
-search path.@refill
+the current directory, in directories specified by matching @code{vpath}
+search paths and the @code{VPATH} search path, and then in the
+directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
+(normally @file{/usr/local/lib}).
 
 For example,
 
@@ -1879,7 +1903,7 @@ clean:
 Because the @code{rm} command does not create a file named @file{clean},
 probably no such file will ever exist.  Therefore, the @code{rm} command
 will be executed every time you say @samp{make clean}.
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
 
 @findex .PHONY
 The phony target will cease to work if anything ever does create a file
@@ -1927,7 +1951,6 @@ makefile @file{./Makefile}.  Since the target remade by default will be the
 first one in the makefile, it is common to make this a phony target named
 @samp{all} and give it, as dependencies, all the individual programs.  For
 example:
-@cindex @code{all}
 
 @example
 all : prog1 prog2 prog3
@@ -1952,6 +1975,8 @@ of the other.  For example, here @samp{make cleanall} will delete the
 object files, the difference files, and the file @file{program}:
 
 @example
+.PHONY: cleanall cleanobj cleandiff
+
 cleanall : cleanobj cleandiff
         rm program
 
@@ -1967,7 +1992,7 @@ cleandiff :
 @cindex force targets
 @cindex targets, force
 @cindex @code{FORCE}
-@cindex rules, no commands or dependencies
+@cindex rule, no commands or dependencies
 
 If a rule has no dependencies or commands, and the target of the rule
 is a nonexistent file, then @code{make} imagines this target to have
@@ -2023,8 +2048,8 @@ print: foo.c bar.c
         touch print
 @end example
 @cindex @code{print} target
-@pindex lpr @r{(shell command)}
-@pindex touch @r{(shell command)}
+@cindex @code{lpr} (shell command)
+@cindex @code{touch} (shell command)
 
 @noindent
 With this rule, @samp{make print} will execute the @code{lpr} command if
@@ -2061,15 +2086,16 @@ of suffixes to be used in checking for suffix rules.
 @item .DEFAULT
 
 The commands specified for @code{.DEFAULT} are used for any target for
-which no rules are found (either explicit rules or implicit rules).  If
-@code{.DEFAULT} commands are specified, every file mentioned as a
-dependency, but not as a target in a rule, will have these commands
-executed on its behalf.  @xref{Search Algorithm, ,Implicit Rule Search
-Algorithm}.
+which no rules are found (either explicit rules or implicit rules).
+@xref{Last Resort}.  If @code{.DEFAULT} commands are specified, every
+file mentioned as a dependency, but not as a target in a rule, will have
+these commands executed on its behalf.  @xref{Search Algorithm,
+,Implicit Rule Search Algorithm}.
 
 @findex .PRECIOUS
 @item .PRECIOUS
 @cindex precious targets
+@cindex preserving with @code{.PRECIOUS}
 
 The targets which @code{.PRECIOUS} depends on are given this special
 treatment: if @code{make} is killed or interrupted during the
@@ -2124,7 +2150,7 @@ both pieces to the suffix list.  In practice, suffixes normally begin with
 @cindex multiple targets
 @cindex several targets in a rule
 @cindex targets, multiple
-@cindex rules, with multiple targets
+@cindex rule, with multiple targets
 
 A rule with multiple targets is equivalent to writing many rules, each with
 one target, and all identical aside from that.  The same commands apply to
@@ -2173,7 +2199,9 @@ littleoutput : text.g
 @noindent
 Here we assume the hypothetical program @code{generate} makes two
 types of output, one if given @samp{-big} and one if given
-@samp{-little}.@refill
+@samp{-little}.
+@xref{Text Functions, ,Functions for String Substitution and Analysis},
+for an explanation of the @code{subst} function.
 @end itemize
 
 Suppose you would like to vary the dependencies according to the target,
@@ -2186,7 +2214,7 @@ do it with a @dfn{static pattern rule}.
 @section Multiple Rules for One Target
 @cindex multiple rules for one target
 @cindex several rules for one target
-@cindex rules, multiple for one target
+@cindex rule, multiple for one target
 @cindex target, multiple rules for one
 
 One file can be the target of several rules.  All the dependencies
@@ -2242,11 +2270,11 @@ searches for an applicable implicit rule to find some commands
 
 @node Static Pattern, Multiple Rules, Multiple Targets, Rules
 @section Static Pattern Rules
-@cindex static pattern rules
-@cindex rules, static pattern
+@cindex static pattern rule
+@cindex rule, static pattern
 @cindex pattern rules, static (not implicit)
 @cindex varying dependencies
-@cindex dependencies, varying
+@cindex dependencies, varying (static pattern)
 
 @dfn{Static pattern rules} are rules which specify multiple targets and
 construct the dependency names for each target based on the target name.
@@ -2278,6 +2306,8 @@ The targets can contain wildcard characters, just like the targets of
 ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
 Names}).
 
+@cindex target pattern, static (not implicit)
+@cindex stem
 The @var{target-pattern} and @var{dep-patterns} say how to compute the
 dependencies of each target.  Each target is matched against the
 @var{target-pattern} to extract a part of the target name, called the
@@ -2291,6 +2321,7 @@ pattern must match exactly.  For example, the target @file{foo.o} matches
 the pattern @samp{%.o}, with @samp{foo} as the stem.  The targets
 @file{foo.c} and @file{foo.out} do not match that pattern.@refill
 
+@cindex dependency pattern, static (not implicit)
 The dependency names for each target are made by substituting the stem
 for the @samp{%} in each dependency pattern.  For example, if one
 dependency pattern is @file{%.c}, then substitution of the stem
@@ -2298,10 +2329,11 @@ dependency pattern is @file{%.c}, then substitution of the stem
 to write a dependency pattern that does not contain @samp{%}; then this
 dependency is the same for all targets.
 
-@cindex backslash (@code{\}), to quote @code{%}
-@cindex @code{\} (backslash), to quote @code{%}
-@cindex quoting @code{%} with @code{\}
+@cindex @code{%}, quoting in static pattern
 @cindex @code{%}, quoting with @code{\} (backslash)
+@cindex @code{\} (backslash), to quote @code{%}
+@cindex backslash (@code{\}), to quote @code{%}
+@cindex quoting @code{%}, in static pattern
 @samp{%} characters in pattern rules can be quoted with preceding
 backslashes (@samp{\}).  Backslashes that would otherwise quote @samp{%}
 characters can be quoted with more backslashes.  Backslashes that quote
@@ -2343,7 +2375,6 @@ $(filter %.o,$(files)): %.o: %.c
 $(filter %.elc,$(files)): %.elc: %.el
         emacs -f batch-byte-compile $<
 @end example
-@pindex emacs
 
 @noindent
 Here the result of @samp{$(filter %.o,$(files))} is @file{bar.o lose.o},
@@ -2352,10 +2383,24 @@ be updated by compiling the corresponding C source file.  The result of
 @w{@samp{$(filter %.elc,$(files))}} is @file{foo.elc}, so that file is
 made from @file{foo.el}.@refill
 
+Another example shows how to use @code{$*} in static pattern rules:
+@vindex $*@r{, and static pattern}
+
+@example
+@group
+bigoutput littleoutput : %output : text.g
+        generate text.g -$* > $@@
+@end group
+@end example
+
+@noindent
+When the @code{generate} command is run, @code{$*} will expand to the
+stem, either @samp{big} or @samp{little}.
+
 @node Static versus Implicit,  , Static Usage, Static Pattern
 @subsection Static Pattern Rules versus Implicit Rules
-@cindex rules, static pattern versus implicit
-@cindex static pattern rules, versus implicit
+@cindex rule, static pattern versus implicit
+@cindex static pattern rule, versus implicit
 
 A static pattern rule has much in common with an implicit rule defined as a
 pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
@@ -2395,7 +2440,7 @@ to precisely the targets specified.
 @node Double-Colon,  , Multiple Rules, Rules
 @section Double-Colon Rules
 @cindex double-colon rules
-@cindex rules, double-colon (@code{::})
+@cindex rule, double-colon (@code{::})
 @cindex multiple rules for one target (@code{::})
 @cindex @code{::} rules (double-colon)
 
@@ -2467,7 +2512,7 @@ Text on a line before a @samp{#} is not part of the comment.
 @cindex echoing of commands
 @cindex silent operation
 @cindex @code{@@} (in commands)
-@cindex command echoing
+@cindex commands, echoing
 @cindex printing of commands
 
 Normally @code{make} prints each command line before it is executed.
@@ -2486,6 +2531,8 @@ the makefile:
 
 @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},
 echoing is all that happens, no execution.  @xref{Options Summary,
 ,Summary of Options}.  In this case and only this case, even the
@@ -2495,6 +2542,7 @@ 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
@@ -2505,16 +2553,16 @@ started with @samp{@@}.  A rule in the makefile for the special target
 
 @node Execution, Parallel, Echoing, Commands
 @section Command Execution
-@cindex command execution
-@cindex execution of commands
-@cindex shell command execution
+@cindex commands, execution
+@cindex execution, of commands
+@cindex shell command, execution
 @vindex SHELL @r{(command execution)}
 
 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.)
 
-@pindex cd @r{(shell command)}
+@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.  If you want to use @code{cd} to affect the
@@ -2532,7 +2580,8 @@ foo : bar/lose
 @cindex commands, quoting newlines in
 @cindex backslash (@code{\}), in commands
 @cindex @code{\} (backslash), in commands
-@cindex quoting newlines in commands
+@cindex quoting newline, in commands
+@cindex newline, quoting, in commands
 If you would like to split a single shell command into multiple lines of
 text, you must use a backslash at the end of all but the last subline.
 Such a sequence of lines is combined into a single line, by deleting the
@@ -2563,7 +2612,7 @@ Environment}.
 @section Parallel Execution
 @cindex commands, execution in parallel
 @cindex parallel execution
-@cindex execution in parallel
+@cindex execution, in parallel
 @cindex job slots
 @cindex @code{-j}
 @cindex @code{--jobs}
@@ -2678,7 +2727,7 @@ clean:
         -rm -f *.o
 @end group
 @end example
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
 
 @noindent
 This causes @code{rm} to continue even if it is unable to remove a file.
@@ -2729,7 +2778,7 @@ default.
 @cindex interrupt
 @cindex signal
 @cindex deletion of target files
-@cindex targets, deleting on interrupt
+@cindex target, deleting on interrupt
 @cindex killing (interruption)
 
 If @code{make} gets a fatal signal while a command is executing, it may
@@ -2783,11 +2832,14 @@ subsystem:
         $(MAKE) -C subdir
 @end example
 @cindex @code{-C}
+@cindex @code{--directory}
 
 You can write recursive @code{make} commands just by copying this example,
 but there are many things to know about how they work and why, and about
 how the sub-@code{make} relates to the top-level @code{make}.
 
+@c !!! example of many subdirs + many subdir targets
+
 @menu
 * MAKE Variable::               The special effects of using @samp{$(MAKE)}.
 * Variables/Recursion::         How to communicate variables to a sub-@code{make}.
@@ -2816,7 +2868,7 @@ invoked.  If this file name was @file{/bin/make}, then the command executed
 is @samp{cd subdir; /bin/make}.  If you use a special version of
 @code{make} to run the top-level makefile, the same special version will be
 executed for recursive invocations.
-@pindex cd @r{(shell command)}
+@cindex @code{cd} (shell command)
 
 Also, any arguments that define variable values are added to @code{MAKE},
 so the sub-@code{make} gets them too.  Thus, if you do @samp{make
@@ -2839,7 +2891,8 @@ really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would
 require executing the command, and @samp{-t} says not to execute
 commands.@refill
 @cindex @code{-t}, and recursion
-@cindex recursion, and @code{-t} 
+@cindex recursion, and @code{-t}
+@cindex @code{--touch}, and recursion
 
 The special feature makes this do what you want: whenever a command
 line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
@@ -3012,20 +3065,29 @@ processes them as if they had been given as arguments.
 @xref{Options Summary, ,Summary of Options}.
 
 @cindex @code{-C}, and recursion
-@cindex recursion, and @code{-C}
 @cindex @code{-f}, and recursion
-@cindex recursion, and @code{-f}
 @cindex @code{-I}, and recursion
-@cindex recursion, and @code{-I}
 @cindex @code{-o}, and recursion
-@cindex recursion, and @code{-o}
 @cindex @code{-W}, and recursion
+@cindex @code{--directory}, and recursion
+@cindex @code{--file}, and recursion
+@cindex @code{--include-dir}, and recursion
+@cindex @code{--old-file}, and recursion
+@cindex @code{--assume-old}, and recursion
+@cindex @code{--assume-new}, and recursion
+@cindex @code{--new-file}, and recursion
+@cindex recursion, and @code{-C}
+@cindex recursion, and @code{-f}
+@cindex recursion, and @code{-I}
+@cindex recursion, and @code{-o}
 @cindex recursion, and @code{-W}
 The options @samp{-C}, @samp{-f}, @samp{-I}, @samp{-o}, and @samp{-W}
 are not put into @code{MAKEFLAGS}; these options are not passed down.@refill
 
 @cindex @code{-j}, and recursion
+@cindex @code{--jobs}, and recursion
 @cindex recursion, and @code{-j}
+@cindex job slots, and recursion
 The @samp{-j} option is a special case 
 (@pxref{Parallel, ,Parallel Execution}).  If you set
 it to some numeric value, @samp{-j 1} is always put into
@@ -3114,9 +3176,12 @@ make: Leaving directory `/u/gnu/make'.
 when processing is completed.
 
 @cindex @code{-C}, and @code{-w}
+@cindex @code{--directory}, and @code{--print-directory}
 @cindex recursion, and @code{-w}
 @cindex @code{-w}, and @code{-C}
 @cindex @code{-w}, and recursion
+@cindex @code{--print-directory}, and @code{--directory}
+@cindex @code{--print-directory}, and recursion
 Normally, you do not need to specify this option because @samp{make}
 does it for you: @samp{-w} is turned on automatically when you use the
 @samp{-C} option, and in sub-@code{make}s (unless you also use
@@ -3141,7 +3206,7 @@ yacc $(firstword $^)
 mv y.tab.c $@@
 endef
 @end example
-@pindex yacc
+@cindex @code{yacc}
 
 @noindent
 Here @code{run-yacc} is the name of the variable being defined;
@@ -3204,10 +3269,10 @@ from getting implicit commands (from implicit rules or the
 @code{.DEFAULT} special target; @pxref{Implicit Rules} and 
 @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
 
-You may be inclined to define empty command strings for targets that
-are not actual files, but only exist so that their dependencies can be
-remade.  However, this is not the best way to do that, because its
-commands may not be run if the target file actually does exist.
+You may be inclined to define empty command strings for targets that are
+not actual files, but only exist so that their dependencies can be
+remade.  However, this is not the best way to do that, because the
+dependencies may not be remade properly if the target file actually does exist.
 @xref{Phony Targets, ,Phony Targets}, for a better way to do this.
 
 @node Using Variables, Conditionals, Commands, Top
@@ -3262,8 +3327,8 @@ command options (@pxref{Overriding, ,Overriding Variables}).
 @section Basics of Variable References
 @cindex variables, how to reference
 @cindex reference to variables
-@cindex @code{$} (variables)
-@cindex dollar sign (@code{$}), and variables
+@cindex @code{$}, in variable reference
+@cindex dollar sign (@code{$}), in variable reference
 
 To substitute a variable's value, write a dollar sign followed by the name
 of the variable in parentheses or braces: either @samp{$(foo)} or
@@ -3291,8 +3356,8 @@ Variable references work by strict textual substitution.  Thus, the rule
 @example
 @group
 foo = c
-prog.o : prog.c
-        $(foo)$(foo) -$(foo) prog.c
+prog.o : prog.$(foo)
+        $(foo)$(foo) -$(foo) prog.$(foo)
 @end group
 @end example
 
@@ -3538,8 +3603,8 @@ sets @samp{bar} to @samp{a.c b.c c.c}.
 @cindex variables, computed names
 @cindex variables, nested references
 @cindex variables, @samp{$} in name
-@cindex @code{$} in variable name
-@cindex dollar sign (@code{$}) in variable name
+@cindex @code{$}, in variable name
+@cindex dollar sign (@code{$}), in variable name
 
 Computed variable names are a complicated concept needed only for
 sophisticated makefile programming.  For most purposes you need not
@@ -3701,6 +3766,21 @@ as the argument to either the @code{sort} or the @code{strip} function.
 This restriction could be removed in the future if that change is shown
 to be a good idea.
 
+You can also use computed variable names in the left-hand side of a
+variable assignment, or in a @code{define} directive, as in:
+
+@example
+dir = foo
+$(dir)_sources := $(wildcard $(dir)/*.c)
+define $(dir)_print
+lpr $($(dir)_sources)
+endef
+@end example
+
+@noindent
+This example defines the variables @samp{dir}, @samp{foo_sources}, and
+@samp{foo_print}.
+
 Note that @dfn{nested variable references} are quite different from
 @dfn{recursively expanded variables}
 (@pxref{Flavors, ,The Two Flavors of Variables}), though both are
@@ -3709,7 +3789,7 @@ used together in complex ways when doing makefile programming.@refill
 @node Values, Setting, Advanced, Using Variables
 @section How Variables Get Their Values
 @cindex variables, how they get their values
-@cindex values, how variables get them
+@cindex value, how a variable gets it
 
 Variables can get values in several different ways:
 
@@ -3760,6 +3840,9 @@ Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
 definitions can contain variable references which will be expanded before
 the definition is made.  @xref{Flavors, ,The Two Flavors of Variables}.
 
+The variable name may contain function and variable references, which
+are expanded when the line is read to find the actual variable name to use.
+
 There is no limit on the length of the value of a variable except the
 amount of swapping space on the computer.  When a variable definition is
 long, it is a good idea to break it into several lines by inserting
@@ -3779,7 +3862,7 @@ automatically to a new value for each rule; these are called the
 @section The @code{override} Directive
 @findex override
 @cindex overriding with @code{override}
-@cindex variables, overriding
+@cindex variable, overriding
 
 If a variable has been set with a command argument (@pxref{Overriding, ,Overriding Variables}),
 then ordinary assignments in the makefile are ignored.  If you want to set
@@ -3833,7 +3916,7 @@ See the next section for information about @code{define}.
 @findex endef
 @cindex verbatim variable definition
 @cindex defining variables verbatim
-@cindex variables, defining verbatim
+@cindex variable, defining verbatim
 
 Another way to set the value of a variable is to use the @code{define}
 directive.  This directive has an unusual syntax which allows newline
@@ -3847,6 +3930,9 @@ following lines.  The end of the value is marked by a line containing just
 the word @code{endef}.  Aside from this difference in syntax, @code{define}
 works just like @samp{=}: it creates a recursively-expanded variable
 (@pxref{Flavors, ,The Two Flavors of Variables}).
+The variable name may contain function and variable references, which
+are expanded when the directive is read to find the actual variable name
+to use.
 
 @example
 define two-lines
@@ -3886,7 +3972,7 @@ endef
 @node Environment,  , Defining, Using Variables
 @section Variables from the Environment
 
-@cindex variables, environment
+@cindex variable, environment
 @cindex environment
 Variables in @code{make} can come from the environment in which
 @code{make} is run.  Every environment variable that @code{make} sees when
@@ -4109,8 +4195,33 @@ empty value.
 Note that @code{ifdef} only tests whether a variable has a value.  It
 does not expand the variable to see if that value is nonempty.
 Consequently, tests using @code{ifdef} return true for all definitions
-except those like @code{foo =}. To test for an empty value, use
-@w{@code{ifeq ($(foo),)}}.
+except those like @code{foo =}.  To test for an empty value, use
+@w{@code{ifeq ($(foo),)}}.  For example,
+
+@example
+bar =
+foo = $(bar)
+ifdef foo
+frobozz = yes
+else
+frobozz = no
+endif
+@end example
+
+@noindent
+sets @samp{frobozz} to @samp{yes}, while:
+
+@example
+foo =
+ifdef foo
+frobozz = yes
+else
+frobozz = no
+endif
+@end example
+
+@noindent
+sets @samp{frobozz} to @samp{no}.
 
 @item ifndef @var{variable-name}
 If the variable @var{variable-name} has an empty value, the
@@ -4203,7 +4314,8 @@ call, just as a variable might be substituted.
 
 @node Syntax of Functions, Text Functions,  , Functions
 @section Function Call Syntax
-@cindex @code{$} (function call)
+@cindex @code{$}, in function call
+@cindex dollar sign (@code{$}), in function call
 @cindex arguments of functions
 @cindex functions, syntax of
 
@@ -4291,10 +4403,11 @@ matching any number of any characters within a word.  If
 @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
 by the text that matched the @samp{%} in @var{pattern}.@refill
 
-@cindex backslash (@code{\}), to quote @samp{%}
-@cindex @code{\} (backslash), to quote @samp{%}
-@cindex quoting @code{%} in @code{patsubst}
 @cindex @code{%}, quoting in @code{patsubst}
+@cindex @code{%}, quoting with @code{\} (backslash)
+@cindex @code{\} (backslash), to quote @code{%}
+@cindex backslash (@code{\}), to quote @code{%}
+@cindex quoting @code{%}, in @code{patsubst}
 @samp{%} characters in @code{patsubst} function invocations can be
 quoted with preceding backslashes (@samp{\}).  Backslashes that would
 otherwise quote @samp{%} characters can be quoted with more backslashes.
@@ -4714,7 +4827,7 @@ produces the result @samp{foo}.  Although @code{$(firstword
 
 @item $(wildcard @var{pattern})
 @findex wildcard
-@cindex wildcards, function
+@cindex wildcard, function
 The argument @var{pattern} is a file name pattern, typically containing
 wildcard characters (as in shell file name patterns).  The result of
 @code{wildcard} is a space-separated list of the names of existing files
@@ -4813,7 +4926,7 @@ no?), but it is more likely to be a mistake.
 @node Origin Function, Shell Function, Foreach Function, Functions
 @section The @code{origin} Function
 @findex origin
-@cindex variables, origin of
+@cindex variable, origin of
 @cindex origin of variable
 
 The @code{origin} function is unlike most other functions in that it does
@@ -4922,9 +5035,9 @@ Here the redefinition takes place if @samp{$(origin bletch)} returns either
 @node Shell Function,  , Origin Function, Functions
 @section The @code{shell} Function
 @findex shell
-@cindex command expansion
+@cindex commands, expansion
 @cindex backquotes
-@cindex shell commands, function for
+@cindex shell command, function for
 
 The @code{shell} function is unlike any other function except the
 @code{wildcard} function 
@@ -4997,11 +5110,12 @@ things or many others.
 @node Makefile Arguments, Goals,  , Running
 @section Arguments to Specify the Makefile
 @cindex @code{--file}
-@cindex @code{--f}
+@cindex @code{--makefile}
+@cindex @code{-f}
 
 The way to specify the name of the makefile is with the @samp{-f} or
-@samp{--file} option.  For example, @samp{-f altmake} says to use the
-file @file{altmake} as the makefile.
+@samp{--file} option (@samp{--makefile} also works).  For example,
+@samp{-f altmake} says to use the file @file{altmake} as the makefile.
 
 If you use the @samp{-f} flag several times and follow each @samp{-f}
 with an argument, all the specified files are used jointly as
@@ -5136,7 +5250,11 @@ what you want.  Certain options specify other activities for @code{make}.
 @table @samp
 @item -n
 @itemx --just-print
+@itemx --dry-run
+@itemx --recon
 @cindex @code{--just-print}
+@cindex @code{--dry-run}
+@cindex @code{--recon}
 @cindex @code{-n}
 ``No-op''.  The activity is to print what commands would be used to make
 the targets up to date, but not actually execute them.
@@ -5145,7 +5263,7 @@ the targets up to date, but not actually execute them.
 @itemx --touch
 @cindex @code{--touch}
 @cindex touching files
-@cindex targets, touching
+@cindex target, touching
 @cindex @code{-t}
 ``Touch''.  The activity is to mark the targets as up to date without
 actually changing them.  In other words, @code{make} pretends to compile
@@ -5162,8 +5280,12 @@ words, neither compilation nor output will occur.
 
 @item -W
 @itemx --what-if
+@itemx --assume-new
+@itemx --new-file
 @cindex @code{--what-if}
 @cindex @code{-W}
+@cindex @code{--assume-new}
+@cindex @code{--new-file}
 @cindex what if
 @cindex files, assuming new
 ``What if''.  Each @samp{-W} flag is followed by a file name.  The given
@@ -5219,6 +5341,7 @@ information about @code{make} or about the makefiles in use
 @section Avoiding Recompilation of Some Files
 @cindex @code{-o}
 @cindex @code{--old-file}
+@cindex @code{--assume-old}
 @cindex files, assuming old
 @cindex files, avoiding recompilation of
 @cindex recompilation, avoiding
@@ -5271,9 +5394,9 @@ Touch all the object files with @samp{make -t}.
 @node Overriding, Testing, Avoiding Compilation, Running
 @section Overriding Variables
 @cindex overriding variables with arguments
-@cindex variables, overriding with arguments
+@cindex variable, overriding with arguments
 @cindex command line variables
-@cindex variables, command line
+@cindex variable, command line
 
 An argument that contains @samp{=} specifies the value of a variable:
 @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
@@ -5392,6 +5515,8 @@ This is typically used with recursive invocations of @code{make}
 @cindex @code{-d}
 @itemx --debug
 @cindex @code{--debug}
+@c Extra blank line here makes the table look better.
+
 Print debugging information in addition to normal processing.  The
 debugging information says which files are being considered for
 remaking, which file-times are being compared and with what results,
@@ -5420,6 +5545,8 @@ Read the file named @var{file} as a makefile.
 @cindex @code{-h}
 @itemx --help
 @cindex @code{--help}
+@c Extra blank line here makes the table look better.
+
 Remind you of the options that @code{make} understands and then exit.
 
 @item -i
@@ -5476,6 +5603,8 @@ limit.  @xref{Parallel, ,Parallel Execution}.
 @cindex @code{--dry-run}
 @itemx --recon
 @cindex @code{--recon}
+@c Extra blank line here makes the table look better.
+
 Print the commands that would be executed, but do not execute them.
 @xref{Instead of Execution, ,Instead of Executing the Commands}.
 
@@ -5528,6 +5657,8 @@ Rules}).  But you can still define your own suffixes with a rule for
 @cindex @code{--silent}
 @itemx --quiet
 @cindex @code{--quiet}
+@c Extra blank line here makes the table look better.
+
 Silent operation; do not print the commands as they are executed.
 @xref{Echoing, ,Command Echoing}.
 
@@ -5537,6 +5668,8 @@ Silent operation; do not print the commands as they are executed.
 @cindex @code{--no-keep-going}
 @itemx --stop
 @cindex @code{--stop}
+@c Extra blank line here makes the table look better.
+
 Cancel the effect of the @samp{-k} option.  This is never necessary
 except in a recursive @code{make} where @samp{-k} might be inherited
 from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion, ,Recursive Use of @code{make}})
@@ -5546,6 +5679,8 @@ or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
 @cindex @code{-t}
 @itemx --touch
 @cindex @code{--touch}
+@c Extra blank line here makes the table look better.
+
 Touch files (mark them up to date without really changing them)
 instead of running their commands.  This is used to pretend that the
 commands were done, in order to fool future invocations of
@@ -5576,8 +5711,8 @@ see @ref{-w Option, ,The @samp{--print-directory} Option}.)
 @cindex @code{-W}
 @itemx --what-if @var{file}
 @cindex @code{--what-if}
-@itemx --new @var{file}
-@cindex @code{--new}
+@itemx --new-file @var{file}
+@cindex @code{--new-file}
 @itemx --assume-new @var{file}
 @cindex @code{--assume-new}
 Pretend that the target @var{file} has just been modified.  When used
@@ -5765,8 +5900,8 @@ a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
 @cindex C++, rule to compile
 @pindex g++
 @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
-@file{@var{n}.C} with a command of the form @samp{$(C++) -c $(CPPFLAGS)
-$(C++FLAGS)}.  We encourage you to use the suffix @samp{.cc} for C++
+@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
@@ -5822,7 +5957,7 @@ running the assembler, @code{as}.  The precise command is
 @samp{$(AS) $(ASFLAGS)}.@refill
 
 @file{@var{n}.s} is made automatically from @file{@var{n}.S} by
-running the C preprocessor, @code{cpp}.  The precise command used is
+running the C preprocessor, @code{cpp}.  The precise command is
 @w{@samp{$(CPP) $(CPPFLAGS)}}.
 
 @item Linking a single object file
@@ -6039,8 +6174,8 @@ Program for doing assembly; default @samp{as}.
 Program for compiling C programs; default @samp{cc}.
 @pindex cc
 
-@item C++
-@vindex C++
+@item CXX
+@vindex CXX
 Program for compiling C++ programs; default @samp{g++}.
 @pindex g++
 
@@ -6148,8 +6283,8 @@ invoked on a @samp{.s} or @samp{.S} file).
 @vindex CFLAGS
 Extra flags to give to the C compiler.
 
-@item C++FLAGS
-@vindex C++FLAGS
+@item CXXFLAGS
+@vindex CXXFLAGS
 Extra flags to give to the C++ compiler.
 
 @item COFLAGS
@@ -6195,7 +6330,7 @@ Extra flags to give to Yacc.
 @section Chains of Implicit Rules
 
 @cindex chains of rules
-@cindex rules, implicit, chains of
+@cindex rule, implicit, chains of
 Sometimes a file can be made by a sequence of implicit rules.  For example,
 a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
 first Yacc and then @code{cc}.  Such a sequence is called a @dfn{chain}.
@@ -6230,7 +6365,7 @@ see @ref{Interrupts}.)@refill
 @cindex intermediate files, preserving
 @cindex preserving intermediate files
 @cindex preserving with .PRECIOUS
-@cindex @code{.PRECIOUS} files
+@cindex @code{.PRECIOUS} intermediate files
 
 A chain can involve more than two implicit rules.  For example, it is
 possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
@@ -6291,7 +6426,7 @@ A pattern rule contains the character @samp{%} (exactly one of them)
 in the target; otherwise, it looks exactly like an ordinary rule.  The
 target is a pattern for matching file names; the @samp{%} matches any
 nonempty substring, while other characters match only themselves.
-@cindex target pattern
+@cindex target pattern, implicit
 @cindex @code{%}, in pattern rules
 
 For example, @samp{%.c} as a pattern matches any file name that ends in
@@ -6305,7 +6440,7 @@ that was matched by the @samp{%} in the target.  In order for
 the pattern rule to apply, its target pattern must match the file name
 under consideration, and its dependency patterns must name files that
 exist or can be made.  These files become dependencies of the target.
-@cindex dependency pattern
+@cindex dependency pattern, implicit
 
 Thus, a rule of the form
 
@@ -6338,7 +6473,7 @@ than the one that matches the target in need of a rule are incidental:
 presently in question.  However, when this file's commands are run, the
 other targets are marked as having been updated themselves.
 @cindex multiple targets, in pattern rule
-@cindex targets, multiple in pattern rule
+@cindex target, multiple in pattern rule
 
 The order in which pattern rules appear in the makefile is important
 because the rules are considered in that order.  Of equally applicable
@@ -6409,8 +6544,8 @@ dependencies, and it will execute happily ever after.)@refill
 @node Automatic, Pattern Match, Pattern Examples, Pattern Rules
 @subsection Automatic Variables
 @cindex automatic variables
-@cindex variables, automatic
-@cindex variables, and implicit rules
+@cindex variable, automatic
+@cindex variable, and implicit rule
 
 Suppose you are writing a pattern rule to compile a @samp{.c} file into a
 @samp{.o} file: how do you write the @samp{cc} command so that it operates
@@ -6765,6 +6900,7 @@ You can use a last-resort rule to override part of another makefile.
 @node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules
 @section Old-Fashioned Suffix Rules
 @cindex old-fashioned suffix rules
+@cindex suffix rule
 
 @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
 @code{make}.  Suffix rules are obsolete because pattern rules are more
@@ -6865,7 +7001,7 @@ this variable.
 
 @node Search Algorithm,  , Suffix Rules, Implicit Rules
 @section Implicit Rule Search Algorithm
-@cindex implicit rule search algorithm
+@cindex implicit rule, search algorithm
 @cindex search algorithm, implicit rule
 
 Here is the procedure @code{make} uses for searching for an implicit rule
@@ -6976,7 +7112,8 @@ main use is as subroutine libraries for linking.
 @menu
 * Archive Members::             Archive members as targets.
 * Archive Update::              The implicit rule for archive member targets.
-* !!! ::                        the .X.a kludge
+* Archive Suffix Rules::        You can write a special kind of suffix rule
+                                  for updating archives.
 @end menu
 
 @node Archive Members, Archive Update,  , Archives
@@ -7026,7 +7163,7 @@ into the archive.  For example, it will update the archive member target
 archive @file{foo.a} as a @emph{member} named @file{bar.o}.
 
 When this rule is chained with others, the result is very powerful.
-Thus, @samp{make "foo.a(bar.o)"} (the quotes are need to protect the
+Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
 @samp{(} and @samp{)} from being interpreted specially by the shell) in
 the presence of a file @file{bar.c} is enough to cause the following
 commands to be run, even without a makefile:
@@ -7062,6 +7199,10 @@ named @file{foo.o}.  In connection with such usage, the automatic variables
 * Archive Symbols::             How to update archive symbol directories.
 @end menu
 
+@node Archive Suffix Rules
+@subsection
+@c !!! new section here for .X.a
+
 @node Archive Symbols,  ,  , Archive Update
 @subsection Updating Archive Symbol Directories
 @cindex __.SYMDEF
@@ -7102,10 +7243,14 @@ updates the @file{__.SYMDEF} member automatically.
 @node Features, Missing, Archives, Top
 @chapter Features of GNU @code{make}
 @cindex features of GNU @code{make}
+@cindex portability
+@cindex compatibility
 
 Here is a summary of the features of GNU @code{make}, for comparison
-with and credit to other versions of @code{make}.  We consider the features
-of @code{make} in 4.2 BSD systems as a baseline.
+with and credit to other versions of @code{make}.  We consider the
+features of @code{make} in 4.2 BSD systems as a baseline.  If you are
+concerned with writing portable makefiles, you should use only the
+features of @code{make} @emph{not} listed here or in @ref{Missing}.
 
 Many features come from the version of @code{make} in System V.
 
@@ -7119,6 +7264,8 @@ It is documented in 4.3 BSD @code{make} (which says it mimics System V's
 
 @item
 Included makefiles.  @xref{Include, ,Including Other Makefiles}.
+Allowing multiple files to be included with a single directive is a GNU
+extension.
 
 @item
 Variables are read from and communicated via the environment.
@@ -7323,7 +7470,7 @@ Various new built-in implicit rules.
 @cindex features, missing
 
 The @code{make} programs in various other systems support a few features
-that are not implemented in GNU @code{make}.  Draft 11.1 of the POSIX.2
+that are not implemented in GNU @code{make}.  Draft 11.2 of the POSIX.2
 standard which specifies @code{make} does not require any of these
 features.@refill
 
@@ -7413,8 +7560,9 @@ using EFL, we will gladly add them.
 
 This appendix summarizes the directives, text manipulation functions,
 and special variables which GNU @code{make} understands.
-@xref{Special Targets}, and @ref{Catalogue of Rules, ,Catalogue of
-Implicit Rules}, for other summaries.
+@xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules},
+and @ref{Options Summary, ,Summary of Options}.
+for other summaries.
 
 Here is a summary of the directives GNU @code{make} recognizes:
 
@@ -7690,9 +7838,8 @@ a makefile to set flags.@*
 The default list of suffixes before @code{make} reads any makefiles.
 @end table
 
-@c !!! this is a pretty lame example --roland
 @node Complex Makefile, Concept Index, Quick Reference, Top
-@appendix A Complex Makefile Example
+@appendix Complex Makefile Example
 
 Here is the makefile for the GNU @code{tar} program.  This is a
 moderately complex makefile.
@@ -7870,12 +8017,12 @@ all:    tar rmt tar.info
 
 @group
 tar:    $(OBJS)
-        $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
+        $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
 @end group
 
 @group
 rmt:    rmt.c
-        $(CC) $(CFLAGS) $(LDFLAGS) -o $@ rmt.c
+        $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
 @end group
 
 @group
@@ -7903,7 +8050,7 @@ testpad.h: testpad
 
 @group
 testpad: testpad.o
-        $(CC) -o $@ testpad.o
+        $(CC) -o $@@ testpad.o
 @end group
 
 @group