Improve description of -local and -hook targets.

* doc/automake.texi (Install, Hard-Coded Install Paths):  Fix
punctuation and markup.
(Extending): Improve wording and clarify order semantics of
*-local and *-hook targets.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

diff --git a/ChangeLog b/ChangeLog
index 3406c4184615111f5faf0c6d808c4227774d00da..adcf1db9af9298c876d7dc09c58f97c837520e38 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2008-06-04  Karl Berry  <karl@freefriends.org>
+
+       * doc/automake.texi (Install, Hard-Coded Install Paths):  Fix
+       punctuation and markup.
+       (Extending): Improve wording and clarify order semantics of
+       *-local and *-hook targets.
+
 2008-06-01  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
        * doc/automake.texi (Extending): Fix grammar.

diff --git a/doc/automake.texi b/doc/automake.texi
index 5517831525c209c0e39d4ce3163287b2ed40a8ab..5c601dc9ec979831783fb79c64b50407cb77455d 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -7783,7 +7783,7 @@ Automake also supports two install hooks, @code{install-exec-hook} and
 @code{install-data-hook}.  These hooks are run after all other install
 rules of the appropriate type, exec or data, have completed.  So, for
 instance, it is possible to perform post-installation modifications
-using an install hook.  @ref{Extending} gives some examples.
+using an install hook.  @xref{Extending}, for some examples.
 @cindex Install hook
 
 @section Staged installs
@@ -9280,23 +9280,28 @@ clean-local:
         -rm -rf testSubDir
 @end example
 
-Older version of this manual used to show how to use
-@code{install-data-local} to install a file to some hard-coded
-location, but you should avoid this.  (@pxref{Hard-Coded Install Paths})
+You may be tempted to use @code{install-data-local} to install a file
+to some hard-coded location, but you should avoid this
+(@pxref{Hard-Coded Install Paths}).
+
+With the @code{-local} targets, there is no particular guarantee of
+execution order; typically, they are run early, but with parallel
+make, there is no way to be sure of that.
 
 @cindex @option{-hook} targets
 @cindex hook targets
-
-Some rules also have a way to run another rule, called a @dfn{hook},
-after their work is done.  The hook is named after the principal target,
-with @samp{-hook} appended.  The targets allowing hooks are
-@code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
-and @code{distcheck}.
 @trindex install-data-hook
 @trindex install-exec-hook
 @trindex uninstall-hook
 @trindex dist-hook
 
+In contrast, some rules also have a way to run another rule, called a
+@dfn{hook}; these are always executed after their work is done.  The
+hook is named after the principal target, with @samp{-hook} appended.
+The targets allowing hooks are @code{install-data},
+@code{install-exec}, @code{uninstall}, @code{dist}, and
+@code{distcheck}.
+
 For instance, here is how to create a hard link to an installed program:
 
 @example
@@ -10883,7 +10888,7 @@ should not be concerned by such site policies: use the appropriate
 standard directory variable to install your files so that installer
 can easily redefine these variables to match their site conventions.
 
-Installing files that should be used by another package, is slightly
+Installing files that should be used by another package is slightly
 more involved.  Let's take an example and assume you want to install
 shared library that is a Python extension module.  If you ask Python
 where to install the library, it will answer something like this: