[automake-commit] branch master updated: doc: overview of autotools ordering.

[Karl Berry]

This is an automated email from the git hooks/post-receive script.

karl pushed a commit to branch master
in repository automake.

View the commit online:
https://git.savannah.gnu.org/gitweb/?p=automake.git;a=commitdiff;h=ea454b4f5a7d8e283e2298fa737598238f4d3840

The following commit(s) were added to refs/heads/master by this push:
     new ea454b4f5 doc: overview of autotools ordering.
ea454b4f5 is described below

commit ea454b4f5a7d8e283e2298fa737598238f4d3840
Author: Karl Berry <karl@freefriends.org>
AuthorDate: Sun Dec 31 18:28:10 2023 -0800

    doc: overview of autotools ordering.
    
    * doc/automake.texi (Creating amhello): briefly mention the order
    in which to run the autotools, a la autoreconf. A couple other tweaks.
---
 doc/automake.texi | 38 ++++++++++++++++++++++++++------------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/doc/automake.texi b/doc/automake.texi
index 72f8336b7..e545eec5e 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -1571,23 +1571,37 @@ amhello-1.0.tar.gz
 =============================================
 @end example
 
-Note that running @command{autoreconf} is only needed initially when
+Running @command{autoreconf} is only needed initially, when
 the GNU Build System does not exist.  When you later change some
 instructions in a @file{Makefile.am} or @file{configure.ac}, the
 relevant part of the build system will be regenerated automatically
 when you execute @command{make}.
 
 @command{autoreconf} is a script that calls @command{autoconf},
-@command{automake}, and a bunch of other commands in the right order.
-If you are beginning with these tools, it is not important to figure
-out in which order all of these tools should be invoked and why.  However,
-because Autoconf and Automake have separate manuals, the important
-point to understand is that @command{autoconf} is in charge of
-creating @file{configure} from @file{configure.ac}, while
-@command{automake} is in charge of creating @file{Makefile.in}s from
-@file{Makefile.am}s and @file{configure.ac}.  This should at least
-direct you to the right manual when seeking answers.
+@command{automake}, and related commands in the right order.  If you
+are beginning with these tools, it is not important to figure out in
+which order all of these tools should be invoked and why. (But for the
+curious: the basic idea is to run:
 
+@enumerate
+@item @command{aclocal} (@pxref{aclocal Invocation}),
+@item @command{autoconf} (@pxref{,,,autoconf, The Autoconf Manual}),
+@item (if needed) @command{autoheader} (part of the
+Autoconf distribution), and
+@item @command{automake} (@pxref{automake Invocation}).
+@end enumerate
+
+@noindent
+If needed, Gettext-related tools (@pxref{,,,gettext, GNU gettext
+utilities}) may be invoked at different points.  Thus, all in all,
+using @command{autoreconf} is quite a bit more convenient.
+
+Nevertheless, because Autoconf and Automake have separate manuals, an
+essential idea to understand is that Autoconf is in charge of creating
+@file{configure} from @file{configure.ac}, while Automake is in charge
+of creating @file{Makefile.in}s from @file{Makefile.am}s and
+@file{configure.ac}.  This should at least direct you to the right
+manual when seeking answers.
 
 @node amhello's configure.ac Setup Explained
 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
@@ -3965,14 +3979,14 @@ The new implementation will probably be done slightly 
differently.
 For instance, it could enforce the @file{m4/}-style layout discussed in
 @ref{Local Macros}.
 
-We have no idea when and how this will happen.  This has been
+We do not know when or whether this will happen.  This has been
 discussed several times in the past, but someone still has to commit
 to that non-trivial task.
 
 From the user point of view, @command{aclocal}'s removal might turn
 out to be painful.  There is a simple precaution that you may take to
 make that switch more seamless: never call @command{aclocal} yourself.
-Keep this guy under the exclusive control of @command{autoreconf} and
+Keep its invocation under the exclusive control of @command{autoreconf} and
 Automake's rebuild rules.  Hopefully you won't need to worry about
 things breaking; when @command{aclocal} disappears, because everything
 will have been taken care of.  If otherwise you used to call