Formerly make.texinfo.~43~

1 files changed, 129 insertions, 99 deletions

diff --git a/make.texinfo b/make.texinfo
index e91af43..9ed3a4a 100644
--- a/make.texinfo
+++ b/make.texinfo
@@ -6,9 +6,9 @@
 @smallbook
 @c %**end of header
 
-@set EDITION 0.35 Beta
+@set EDITION 0.35 Beta in the middle of being turned into 0.36 and I left off at page 36
 @set VERSION 3.63 Beta
-@set UPDATED 18 August 1992
+@set UPDATED 19 August 1992
 @set UPDATE-MONTH August 1992
 
 @c finalout
@@ -350,7 +350,7 @@ files should be recompiled, or how.  @xref{make Invocation, ,How to Run
 @code{make}}.
 
 @node Reading, Bugs, Preparing, Overview
-@section On Reading this Text
+@section On Reading this Text   @c !!!!! I don't like this title --roland
 
 If you are new to @code{make}, or are looking for a general
 introduction, read the first few sections of each chapter, skipping the
@@ -360,10 +360,11 @@ specialized or technical information.  The exception is the second
 chapter, @ref{Introduction, ,An Introduction to Makefiles}, all of which
 is introductory.
 
-If you are familiar with other @code{make} programs, see
-@ref{Features}, which lists the enhancements GNU @code{make} has, and
-@ref{Missing}, which explains the few things GNU @code{make} lacks
-that others have.
+If you are familiar with other @code{make} programs, see @ref{Features,
+,Features of GNU @code{make}}, which lists the enhancements GNU
+@code{make} has, and @ref{Missing, ,Incompatibilities and Missing
+Features}, which explains the few things GNU @code{make} lacks that
+others have.
 
 For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
 and @ref{Special Targets}.
@@ -402,8 +403,7 @@ through the Internet or via UUCP:
 
 @noindent
 Please include the version number of @code{make} you are using.  You can
-get this information with the command @samp{make -v -f
-/dev/null}.@refill
+get this information with the command @samp{make --version -f /dev/null}.
 
 Non-bug suggestions are always welcome as well.  If you have questions
 about things that are unclear in the documentation or are just obscure
@@ -479,17 +479,18 @@ A simple makefile consists of ``rules'' with the following shape:
 
 A @dfn{target} is usually the name of a file that is generated by a
 program; examples of targets are executable or object files.  A target
-can also be the name of an action to carry out, such as @samp{clean}.
+can also be the name of an action to carry out, such as @samp{clean}
+(@pxref{Phony Targets}).
 
 A @dfn{dependency} is a file that is used as input to create the
 target.  A target often depends on several files.  
 
 A @dfn{command} is an action that @code{make} carries out.
 A rule may have more than one command, each on its own line.
-@emph{Please note:} you need to put a @key{TAB} at the beginning of
+@strong{Please note:} you need to put a @key{TAB} at the beginning of
 every command line!  This is an obscurity that catches the unwary.
 
-Often a command is in a rule with dependencies and serves to create a
+Usually a command is in a rule with dependencies and serves to create a
 target file if any of the dependencies change.  However, the rule that
 specifies commands for the target need not have dependencies.  For
 example, the rule containing the delete command associated with the
@@ -587,8 +588,10 @@ specified when the target file needs to be updated.)
 
 The target @samp{clean} is not a file, but merely the name of an
 action; so @code{make} never does anything with it unless you tell it
-specifically.  (Note that this rule does not have any dependencies.
-@xref{Phony Targets, ,Phony Targets}, to see how to prevent a real file called
+specifically.
+@c !!! 1st sentence in parens bad -rm
+(Note that this rule does not have any dependencies.
+@xref{Phony Targets}, to see how to prevent a real file called
 @file{clean} from causing confusion.  @xref{Errors, , Errors in
 Commands}, to see how to force @code{rm} to work in spite of errors.)
 
@@ -648,7 +651,7 @@ Thus, if we change the file @file{insert.c} and run @code{make},
 @code{make} will compile that file to update @file{insert.o}, and then
 link @file{edit}.  If we change the file @file{command.h} and run
 @code{make}, @code{make} will recompile the object files @file{kbd.o},
-@file{command.o} and @file{files.o} and then link file @file{edit}.
+@file{command.o} and @file{files.o} and then link the file @file{edit}.
 
 @node Variables Simplify, make Deduces, How Make Works, Introduction
 @section Variables Make Makefiles Simpler
@@ -680,7 +683,7 @@ such a variable @code{objects} with a line like this in the makefile:@refill
 @example
 @group
 objects = main.o kbd.o command.o display.o \
-              insert.o search.o files.o utils.o
+          insert.o search.o files.o utils.o
 @end group
 @end example
 
@@ -695,7 +698,7 @@ for the object files:
 @example
 @group
 objects = main.o kbd.o command.o display.o \
-              insert.o search.o files.o utils.o
+          insert.o search.o files.o utils.o
 
 edit : $(objects)
         cc -o edit $(objects)
@@ -740,8 +743,8 @@ Here is the entire example, with both of these changes, and a variable
 
 @example
 @group
-objects =  main.o kbd.o command.o display.o \
- insert.o search.o files.o utils.o
+objects = main.o kbd.o command.o display.o \
+          insert.o search.o files.o utils.o
 
 edit : $(objects)
         cc -o edit $(objects)
@@ -779,8 +782,8 @@ Here is what one looks like:
 
 @example
 @group
-objects =  main.o kbd.o command.o display.o \
- insert.o search.o files.o utils.o
+objects = main.o kbd.o command.o display.o \
+          insert.o search.o files.o utils.o
 
 edit : $(objects)
         cc -o edit $(objects)
@@ -831,6 +834,7 @@ clean :
 @end example
 
 @noindent
+@c !!!! wrong -rm
 This prevents @code{make} from getting confused by an actual file
 called @file{clean} and empowers @code{rm} to continue in spite of errors.
 (See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.)
@@ -844,6 +848,7 @@ the editor, to remain the default goal.
 Since @code{clean} is not a dependency of @code{edit}, this rule will not
 run at all if we give the command @samp{make} with no arguments.  In
 order to make the rule run, we have to type @samp{make clean}.
+@xref{make Invocation, ,How to Run @code{make}}.
 
 @node Makefiles, Rules, Introduction, Top
 @chapter Writing Makefiles
@@ -865,17 +870,19 @@ reading a data base called the @dfn{makefile}.
 @node Makefile Contents, Makefile Names,  , Makefiles
 @section What Makefiles Contain
 
+@c !!!! want to mention implicit rules here somehow --roland
+
 Makefiles contain four kinds of things: @dfn{rules}, @dfn{variable
-definitions}, @dfn{directives}, and @dfn{comments}.  Rules, variables, and
-directives are described at length in later chapters.@refill
+definitions}, @dfn{directives}, and @dfn{comments}.  Rules, variables,
+and directives are described at length in later chapters.@refill
 
 @itemize @bullet
 @cindex rule (definition of)
 @item
-A @dfn{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}.
+An @dfn{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 variable definition
 @item
@@ -934,7 +941,8 @@ important files such as @file{README}.)  The first name checked,
 @file{GNUmakefile}, is not recommended for most makefiles.  You should
 use this name if you have a makefile that is specific to GNU
 @code{make}, and will not be understood by other versions of
-@code{make}.
+@code{make}.  Other @code{make} programs look for @file{makefile} and
+@file{Makefile}, but not @code{GNUmakefile}.
 
 If @code{make} finds none of these names, it does not use any makefile.
 Then you must specify a goal with a command argument, and @code{make}
@@ -942,14 +950,16 @@ will attempt to figure out how to remake it using only its built-in
 implicit rules.  @xref{Implicit Rules, ,Using Implicit Rules}.
 
 @cindex @code{-f}
+@cindex @code{--file}
 If you want to use a nonstandard name for your makefile, you can specify
-the makefile name with the @samp{-f} option.  The arguments @samp{-f
-@var{name}} tell @code{make} to read the file @var{name} as the
-makefile.  If you use more than one @samp{-f} option, you can specify
-several makefiles.  All the makefiles are effectively concatenated in
-the order specified.  The default makefile names @file{GNUmakefile},
+the makefile name with the @samp{-f} or @samp{--file} option.  The
+arguments @samp{-f @var{name}} or @samp{--file @var{name}} tell
+@code{make} to read the file @var{name} as the makefile.  If you use
+more than one @samp{-f} or @samp{--file} option, you can specify several
+makefiles.  All the makefiles are effectively concatenated in the order
+specified.  The default makefile names @file{GNUmakefile},
 @file{makefile} and @file{Makefile} are not checked automatically if you
-specify @samp{-f}.@refill
+specify @samp{-f} or @samp{--file}.@refill
 
 @node Include, MAKEFILES Variable, Makefile Names, Makefiles
 @section Including Other Makefiles
@@ -1005,9 +1015,9 @@ If the environment variable @code{MAKEFILES} is defined, @code{make}
 considers its value as a list of names (separated by whitespace) of
 additional makefiles to be read before the others.  This works much like
 the @code{include} directive: various directories are searched for those
-files (@pxref{Include, ,Including Other Makefiles}).  In addition, the default goal is never taken
-from one of these makefiles and it is not an error if the files listed
-in @code{MAKEFILES} are not found.@refill
+files (@pxref{Include, ,Including Other Makefiles}).  In addition, the
+default goal is never taken from one of these makefiles and it is not an
+error if the files listed in @code{MAKEFILES} are not found.@refill
 
 The main use of @code{MAKEFILES} is in communication between recursive
 invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
@@ -1016,7 +1026,7 @@ variable before a top-level invocation of @code{make}, because it is
 usually better not to mess with a makefile from outside.  However, if
 you are running @code{make} without a specific makefile, a makefile in
 @code{MAKEFILES} can do useful things to help the built-in implicit
-rules work better, such as defining search paths.@refill
+rules work better, such as defining search paths (@pxref{Directory Search}).
 
 Some users are tempted to set @code{MAKEFILES} in the environment
 automatically on login, and program makefiles to expect this to be done.
@@ -1044,6 +1054,7 @@ and reads all the makefiles over again.  (It will also attempt to update
 each of them over again, but normally this will not change them again,
 since they are already up to date.)@refill
 
+@c !!!! only :: ? -rm
 If the makefiles specify commands to remake a file but no dependencies,
 the file will always be remade.  In the case of makefiles, a makefile
 that has commands but no dependencies will be remade every time
@@ -1067,16 +1078,17 @@ to make each of them in the same order in which they are searched for
 of names to try.  Note that it is not an error if @code{make} cannot
 find or make any makefile; a makefile is not always necessary.@refill
 
-When you use the @samp{-t} option (touch targets), you would not want to
-use an out-of-date makefile to decide which targets to touch.  So the
-@samp{-t} option has no effect on updating makefiles; they are really
-updated even if @samp{-t} is specified.  Likewise, @samp{-q} and
-@samp{-n} do not prevent updating of makefiles, because an out-of-date
-makefile would result in the wrong output for other targets.  Thus,
-@samp{make -f mfile -n foo} will update @file{mfile}, read it in, and
-then print the commands to update @file{foo} and its dependencies
-without running them.  The commands printed for @file{foo} will be those
-specified in the updated contents of @file{mfile}.
+When you use the @samp{-t} or @samp{--touch} option (touch targets), you
+would not want to use an out-of-date makefile to decide which targets to
+touch.  So the @samp{-t} option has no effect on updating makefiles;
+they are really updated even if @samp{-t} is specified.  Likewise,
+@samp{-q} (or @samp{--question}) and @samp{-n} (or @samp{--just-print})
+do not prevent updating of makefiles, because an out-of-date makefile
+would result in the wrong output for other targets.  Thus, @samp{make -f
+mfile -n foo} will update @file{mfile}, read it in, and then print the
+commands to update @file{foo} and its dependencies without running them.
+The commands printed for @file{foo} will be those specified in the
+updated contents of @file{mfile}.
 
 However, on occasion you might actually wish to prevent updating of even
 the makefiles.  You can do this by specifying the makefiles as goals in
@@ -1136,7 +1148,7 @@ will apply the rule.  And likewise for any other target that
 @cindex dependency
 
 A @dfn{rule} appears in the makefile and says when and how to remake
-certain files, called the rule's @dfn{targets} (usually only one per rule).
+certain files, called the rule's @dfn{targets} (most often only one per rule).
 It lists the other files that are the @dfn{dependencies} of the target, and
 @dfn{commands} to use to create or update the target.
 
@@ -1147,13 +1159,13 @@ rule in the first makefile.  If the first rule has multiple targets,
 only the first target is taken as the default.  There are two
 exceptions: a target starting with a period is not a default unless it
 contains one or more slashes, @samp{/}, as well; and, a target that
-defines a pattern rule or a suffix rule has no effect on the default
-goal.  (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules},
-and see @ref{Suffix Rules, ,Old-Fashioned Suffix Rules}.)
+defines a pattern rule has no effect on the default goal.
+(@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
 
 Therefore, we usually write the makefile so that the first rule is the
 one for compiling the entire program or all the programs described by
-the makefile.  @xref{Goals, ,Arguments to Specify the Goals}.
+the makefile (often with a target called @samp{all}).
+@xref{Goals, ,Arguments to Specify the Goals}.
 
 @menu
 * Rule Example::                An example explained.
@@ -1229,7 +1241,7 @@ or like this:
         @dots{}
 @end example
 
-The @var{targets} are file names, separated by spaces.  Wild card
+The @var{targets} are file names, separated by spaces.  Wildcard
 characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
 in File Names}) and a name of the form @file{@var{a}(@var{m})}
 represents member @var{m} in archive file @var{a} 
@@ -1238,8 +1250,8 @@ Usually there is only one
 target per rule, but occasionally there is a reason to have more
 (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
 
-The @var{command} lines start with a tab character.  The first command may
-appear on the line after the dependencies, with a tab character, or may
+The @var{command} lines start with a @key{TAB}.  The first command may
+appear on the line after the dependencies, with a @key{TAB}, or may
 appear on the same line, with a semicolon.  Either way, the effect is the
 same.  @xref{Commands, ,Writing the Commands in Rules}.
 
@@ -1272,13 +1284,18 @@ executed by the shell (normally @samp{sh}), but with some extra features
 @cindex wildcard
 @cindex file name
 
+@cindex * (wildcard character)
+@cindex ? (wildcard character)
+@cindex [@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}
 specifies a list of all the files (in the working directory) whose names
 end in @samp{.c}.@refill
 
-@cindex ~
+@cindex ~ (tilde)
+@cindex tilde (@code{~})
+@cindex home directory
 The character @samp{~} at the beginning of a file name also has special
 significance.  If alone, or followed by a slash, it represents your home
 directory.  For example @file{~/bin} expands to @file{/home/you/bin}.
@@ -1286,9 +1303,10 @@ If the @samp{~} is followed by a word, the string represents the home
 directory of the user named by that word.  For example @file{~john/bin}
 expands to @file{/home/john/bin}.@refill
 
-Wildcard expansion happens automatically in targets, in dependencies, and
-in commands.  In other contexts, wildcard expansion happens only if you
-request it explicitly with the @code{wildcard} function.
+Wildcard expansion happens automatically in targets, in dependencies,
+and in commands (where the shell does the expansion).  In other
+contexts, wildcard expansion happens only if you request it explicitly
+with the @code{wildcard} function.
 
 The special significance of a wildcard character can be turned off by
 preceding it with a backslash.  Thus, @file{foo\*bar} would refer to a
@@ -1333,13 +1351,21 @@ Wildcard expansion does not happen when you define a variable.  Thus, if
 you write this:
 
 @example
-objects=*.o
+objects = *.o
 @end example
 
 @noindent
 then the value of the variable @code{objects} is the actual string
 @samp{*.o}.  However, if you use the value of @code{objects} in a target,
 dependency or command, wildcard expansion will take place at that time.
+To set @code{objects} to the expansion, instead use:
+
+@example
+objects := $(wildcard *.o)
+@end example
+
+@noindent
+@xref{Wildcard Function}.
 
 @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
 @subsection Pitfalls of Using Wildcards
@@ -1350,7 +1376,7 @@ executable file @file{foo} is made from all the object files in the
 directory, and you write this:
 
 @example
-objects=*.o
+objects = *.o
 
 foo : $(objects)
         cc -o foo $(CFLAGS) $(objects)
@@ -1402,31 +1428,31 @@ $(wildcard *.c)
 @end example
 
 We can change the list of C source files into a list of object files by
-substituting @samp{.o} for @samp{.c} in the result, like this:
+replacing the @samp{.o} suffix with @samp{.c} in the result, like this:
 
 @example
-$(subst .c,.o,$(wildcard *.c))
+$(patsubst %.c,%.o,$(wildcard *.c))
 @end example
 
 @noindent
-(Here we have used another function, @code{subst}.
+(Here we have used another function, @code{patsubst}.
 @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
 
 Thus, a makefile to compile all C source files in the directory and then
 link them together could be written as follows:
 
 @example
-objects:=$(subst .c,.o,$(wildcard *.c))
+objects := $(patsubst %.c,%.o,$(wildcard *.c))
 
 foo : $(objects)
-        cc -o foo $(LDFLAGS) $(objects)
+        cc -o foo $(objects)
 @end example
 
 @noindent
 (This takes advantage of the implicit rule for compiling C programs, so
 there is no need to write explicit rules for compiling the files.
-@xref{Flavors, ,The Two Flavors of Variables}, for an explanation of @samp{:=}, which is a variant of
-@samp{=}.)
+@xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
+@samp{:=}, which is a variant of @samp{=}.)
 
 @node Directory Search, Phony Targets, Wildcards, Rules
 @section Searching Directories for Dependencies
@@ -1463,13 +1489,13 @@ current directory; however, @code{VPATH} specifies a search list that
 @code{make} applies for all files, including files which are targets of
 rules.
 
-Thus, if a file that is listed as a dependency does not exist in the
-current directory, @code{make} searches the directories listed in
+Thus, if a file that is listed as a target or dependency does not exist
+in the current directory, @code{make} searches the directories listed in
 @code{VPATH} for a file with that name.  If a file is found in one of
 them, that file becomes the dependency.  Rules may then specify the
 names of source files in the dependencies as if they all existed in the
-current directory.  
-@xref{Commands/Search, ,Writing Shell Commands with Directory Search}.
+current directory.  @xref{Commands/Search, ,Writing Shell Commands with
+Directory Search}.
 
 In the @code{VPATH} variable, directory names are separated by colons.
 The order in which directories are listed is the order followed by
@@ -1518,6 +1544,7 @@ There are three forms of the @code{vpath} directive:
 Specify the search path @var{directories} for file names that match
 @var{pattern}.  If another path was previously specified for the same
 pattern, the new path is effectively appended to the old path.@refill
+@c !!!! above is not quite right --roland
 
 The search path, @var{directories}, is a colon-separated list of
 directories to be searched, just like the search path used in the
@@ -1526,7 +1553,9 @@ directories to be searched, just like the search path used in the
 @item vpath @var{pattern}
 Clear out the search path associated with @var{pattern}.
 
+@c Extra blank line makes sure this gets two lines.
 @item vpath
+
 Clear all search paths previously specified with @code{vpath} directives.
 @end table
 
@@ -1591,25 +1620,16 @@ foo.o : foo.c
 compilation by implicit rule; we use it here for consistency so it will
 affect all C compilations uniformly; @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
 
-Often the dependencies include header files as well, which you do not want
-to mention in the commands.  The function @code{firstword} can be used to
-extract just the first dependency from the entire list, as shown here
-(@pxref{Filename Functions, ,Functions for File Names}):
+Often the dependencies include header files as well, which you do not
+want to mention in the commands.  The automatic variable @samp{$<} is
+just the first dependency:
 
 @example
 VPATH = src:../headers
 foo.o : foo.c defs.h hack.h
-        cc -c $(CFLAGS) $(firstword $^) -o $@@
+        cc -c $(CFLAGS) $< -o $@@
 @end example
 
-@noindent
-@c !!! following paragraph rewritten to avoid overfull hbox
-In this example, the value of @samp{$^} would be a value such as
-@samp{src/foo.c ../headers/defs.h hack.h}; you would use
-@samp{$(firstword $^)} to extract just @samp{src/foo.c}.  Since you want
-to do this so often, the automatic variable @code{$<} is always the
-first dependency, the same as @samp{$(firstword $^)}.@refill
-
 @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
 @subsection Directory Search and Implicit Rules
 
@@ -1624,9 +1644,9 @@ appropriate directories are searched for it.  If @file{foo.c} exists (or is
 mentioned in the makefile) in any of the directories, the implicit rule for
 C compilation is applicable.
 
-The commands of all the built-in implicit rules normally use automatic
-variables as a matter of necessity; consequently they will use the file
-names found by directory search with no extra effort.
+The commands of implicit rules normally use automatic variables as a
+matter of necessity; consequently they will use the file names found by
+directory search with no extra effort.
 
 @node Libraries/Search,  , Implicit/Search, Directory Search
 @subsection Directory Search for Link Libraries
@@ -1674,7 +1694,7 @@ will repeat the appropriate search when it processes this argument.@refill
 A phony target is one that is not really the name of a file.  It is just a
 name for some commands to be executed when you make an explicit request.
 There are two reasons to use a phony target: to avoid a conflict with
-file of the same name, and to improve performance.
+a file of the same name, and to improve performance.
 
 If you write a rule whose commands will not create the target file, the
 commands will be executed every time the target comes up for remaking.
@@ -1706,11 +1726,11 @@ declare the target to be phony, using the special target @code{.PHONY}
 Once this is done, @samp{make clean} will run the commands regardless of
 whether there is a file named @file{clean}.
 
-Since @code{make} knows that phony targets do not name actual files
-that could be remade from other files, @code{make} skips the implicit
-rule search for phony targets (@pxref{Implicit Rules}).  This is why
-declaring a target phony is good for performance, even if you are not
-worried about the actual file existing.
+Since it knows that phony targets do not name actual files that could be
+remade from other files, @code{make} skips the implicit rule search for
+phony targets (@pxref{Implicit Rules}).  This is why declaring a target
+phony is good for performance, even if you are not worried about the
+actual file existing.
 
 Thus, you first write the line that states that @code{clean} is a
 phony target, then you write the rule, like this:
@@ -1796,6 +1816,7 @@ commonly used this way.
 As you can see, using @samp{FORCE} this way has the same results as using
 @samp{.PHONY: clean}.  
 
+@c !!! wrong. FORCE is secure too --roland
 Using @samp{.PHONY} is more explicit, more efficient, and more secure,
 since it protects against the file actually existing.  However, other
 versions of @code{make} do not support @samp{.PHONY}; thus
@@ -1842,6 +1863,7 @@ Certain names have special meanings if they appear as targets.
 
 @table @code
 @item .PHONY
+
 The dependencies of the special target @code{.PHONY} are considered to
 be phony targets.  When it is time to consider such a target,
 @code{make} will run its commands unconditionally, regardless of
@@ -1849,11 +1871,13 @@ whether a file with that name exists or what its last-modification
 time is.  @xref{Phony Targets, ,Phony Targets}.
 
 @item .SUFFIXES
+
 The dependencies of the special target @code{.SUFFIXES} are the list
 of suffixes to be used in checking for suffix rules.  
 @xref{Suffix Rules, , Old-Fashioned 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
@@ -1863,12 +1887,14 @@ Algorithm}.
 
 @item .PRECIOUS
 @cindex precious targets
+
 The targets which @code{.PRECIOUS} depends on are given this special
 treatment: if @code{make} is killed or interrupted during the
 execution of their commands, the target is not deleted.
 @xref{Interrupts, ,Interrupting or Killing @code{make}}.
 
 @item .IGNORE
+
 Simply by being mentioned as a target, @code{.IGNORE} says to ignore
 errors in execution of commands.  The dependencies and commands for
 @code{.IGNORE} are not meaningful.
@@ -1879,16 +1905,20 @@ useful; we recommend you use the more selective ways to ignore errors
 in specific commands.  @xref{Errors, ,Errors in Commands}.
 
 @item .SILENT
+
 Simply by being mentioned as a target, @code{.SILENT} says not to
 print commands before executing them.  The dependencies and commands
 for @code{.SILENT} are not meaningful.
 
 @samp{.SILENT} exists for historical compatibility.  We recommend you
 use the more selective ways to silence specific commands.
-@xref{Echoing, ,Command Echoing}.
+@xref{Echoing, ,Command Echoing}.  If you want to silence all commands
+for a particular run of @code{make}, use the @samp{-s} or
+@samp{--silent} option (@pxref{Options Summary}).
 
 @item .EXPORT_ALL_VARIABLES
-By being mentioned as a target, @code{.EXPORT_ALL_VARIABLES}
+
+Simply by being mentioned as a target, @code{.EXPORT_ALL_VARIABLES}
 tells @code{make} to export all variables to child processes by default.
 @xref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}.
 @end table
@@ -2838,7 +2868,7 @@ commands based on the file names involved (@pxref{Implicit Rules,
 ,Using Implicit Rules}).
 
 @node Empty Commands,  , Sequences, Commands
-@section Defining Empty Commands
+@section Using Empty Commands
 @cindex empty commands
 
 It is sometimes useful to define commands which do nothing.  This is done
@@ -2851,7 +2881,7 @@ target:;
 
 @noindent
 defines an empty command string for @file{target}.  You could also use a
-line beginning with a tab character to define an empty command string,
+line beginning with a @key{TAB} to define an empty command string,
 but this would be confusing because such a line looks empty.
 
 You may be wondering why you would want to define a command string that