Re: -local vs. -hook?

[Karl Berry]

    But that text is what's already in the manual!  

I don't see it.  Maybe I missed it.  If so, sorry.

    Maybe you can put your suggestions in a proposed patch, so that we
    can avoid misunderstanding?

The first and last hunk are unrelated tiny fixes that I just happened to
notice going through the source.  The rest adds the text about execution
order.

karl

--- 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
address@hidden 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
address@hidden, @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
address@hidden; 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},
address@hidden, @code{uninstall}, @code{dist}, and
address@hidden
+
 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: