* doc/make.text (Reading Makefiles): Rewrite to be more clear.

1 files changed, 27 insertions, 25 deletions

diff --git a/doc/make.texi b/doc/make.texi
index 96622678..3e61f298 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -1469,25 +1469,27 @@ build it---otherwise it would apply the same match-anything rule to
 @cindex reading makefiles
 @cindex makefile, reading
 
-GNU @code{make} does its work in two distinct phases.  During the first
-phase it reads all the makefiles, included makefiles, etc. and
-internalizes all the variables and their values, implicit and explicit
-rules, and constructs a dependency graph of all the targets and their
-prerequisites.  During the second phase, @code{make} uses these internal
-structures to determine what targets will need to be rebuilt and to
-invoke the rules necessary to do so.
+GNU @code{make} does its work in two distinct phases.  During the
+first phase it reads all the makefiles, included makefiles, etc. and
+internalizes all the variables and their values and implicit and
+explicit rules, and builds a dependency graph of all the targets and
+their prerequisites.  During the second phase, @code{make} uses this
+internalized data to determine which targets need to be updated and
+run the recipes necessary to update them.
 
 It's important to understand this two-phase approach because it has a
 direct impact on how variable and function expansion happens; this is
-often a source of some confusion when writing makefiles.  Here we will
-present a summary of the phases in which expansion happens for different
-constructs within the makefile.  We say that expansion is
-@dfn{immediate} if it happens during the first phase: in this case
-@code{make} will expand any variables or functions in that section of a
-construct as the makefile is parsed.  We say that expansion is
-@dfn{deferred} if expansion is not performed immediately.  Expansion of
-a deferred construct is not performed until either the construct appears
-later in an immediate context, or until the second phase.
+often a source of some confusion when writing makefiles.  Below is a
+summary of the different constructs that can be found in a makefile,
+and the phase in which expansion happens for each part of the
+construct.
+
+We say that expansion is @dfn{immediate} if it happens during the
+first phase: @code{make} will expand that part of the construct as the
+makefile is parsed.  We say that expansion is @dfn{deferred} if it is
+not immediate.  Expansion of a deferred construct part is delayed
+until the expansion is used: either when it is referenced in an
+immediate context, or when it is needed during the second phase.
 
 You may not be familiar with some of these constructs yet.  You can
 reference this section as you become familiar with them, in later
@@ -1540,14 +1542,14 @@ define @var{immediate} !=
 endef
 @end example
 
-For the append operator, @samp{+=}, the right-hand side is considered
+For the append operator @samp{+=}, the right-hand side is considered
 immediate if the variable was previously set as a simple variable
 (@samp{:=} or @samp{::=}), and deferred otherwise.
 
-For the shell assignment operator, @samp{!=}, the right-hand side is
-evaluated immediately and handed to the shell.  The result is stored in the
-variable named on the left, and that variable becomes a simple variable
-(and will thus be re-evaluated on each reference).
+For the shell assignment operator @samp{!=}, the right-hand side is
+evaluated immediately and handed to the shell.  The result is stored
+in the variable named on the left, and that variable becomes a simple
+variable (and will thus be re-evaluated on each reference).
 
 @subheading Conditional Directives
 @cindex ifdef, expansion
@@ -1576,10 +1578,10 @@ A rule is always expanded the same way, regardless of the form:
         @var{deferred}
 @end example
 
-That is, the target and prerequisite sections are expanded immediately,
-and the recipe used to construct the target is always deferred.  This
-general rule is true for explicit rules, pattern rules, suffix rules,
-static pattern rules, and simple prerequisite definitions.
+That is, the target and prerequisite sections are expanded
+immediately, and the recipe used to build the target is always
+deferred.  This is true for explicit rules, pattern rules, suffix
+rules, static pattern rules, and simple prerequisite definitions.
 
 @node Parsing Makefiles, Secondary Expansion, Reading Makefiles, Makefiles
 @section How Makefiles Are Parsed