[automake-commit] branch master updated: doc: bring a few examples up to date.

[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=7db4d7d1e419df773d8ad4406389d0d21ccd4be0

The following commit(s) were added to refs/heads/master by this push:
     new 7db4d7d1e doc: bring a few examples up to date.
7db4d7d1e is described below

commit 7db4d7d1e419df773d8ad4406389d0d21ccd4be0
Author: Karl Berry <karl@freefriends.org>
AuthorDate: Sat Jun 24 18:31:29 2023 -0700

    doc: bring a few examples up to date.
    
    * doc/automake.texi (Built Sources Example): use @kbd for typed
    commands; show current output.
    (Checking the Distribution): refer to Third-Party Makefiles
    for the do-nothing dvi target example.
    Other small wording tweaks throughout.
    
    * HACKING: consistently omit $ prompt.
    Say a bit more about versions of Autoconf.
    Describe actual current status of branches (only master in use).
    Give some topic examples.
    "rerun" not "re-run".
    Other small wording tweaks throughout.
---
 HACKING           | 39 +++++++++++++++++++++++-----------
 doc/automake.texi | 62 ++++++++++++++++++++++++-------------------------------
 2 files changed, 54 insertions(+), 47 deletions(-)

diff --git a/HACKING b/HACKING
index e0ac01875..bb6b21c06 100644
--- a/HACKING
+++ b/HACKING
@@ -3,14 +3,14 @@
 
 * This file attempts to describe the conventions to use when hacking automake.
 
-* After git checkout from Savannah, can do initial build with, e.g.:
-  $ ./bootstrap && ./configure --prefix=/tmp/amdev && make
+* After git checkout from Savannah, you can do an initial build with, e.g.:
+    ./bootstrap && ./configure --prefix=/tmp/amdev && make
 
 ============================================================================
 = Administrivia
 
 * The correct response to most actual bugs is to write a new test case
-  which demonstrates the bug.  Then fix the bug, re-run the test suite,
+  which demonstrates the bug.  Then fix the bug, rerun the test suite,
   and check everything in.  Run the test suite in parallel or it takes ages.
 
 * If you incorporate a change from somebody on the net:
@@ -63,7 +63,7 @@
   can be automatically fetched using the GNU Guix package manager with the
   following command:
 
-  $ guix environment automake --ad-hoc \
+    guix environment automake --ad-hoc \
       gettext help2man texinfo libtool flex bison dejagnu zip icedtea \
       python gcc-toolchain gfortran pkg-config vala
 
@@ -187,14 +187,23 @@
   use the 'bootstrap' script.  It uses the code from the source
   tree, so the resulting files (aclocal.m4 and Makefile.in) should
   be the same as you would get if you install this version of
-  automake and use it to generate those files.  Be sure to have the
-  latest stable version of Autoconf installed and available early
-  in your PATH. To get a faithful and correct rebuild, run:
+  automake and use it to generate those files. 
+
+* To get a faithful and correct rebuild, run:
     ./bootstrap && ./config.status --recheck && make clean all
-  (per https://bugs.gnu.org/11347)
 
-* The Automake git tree currently carries three basic branches: 'master',
-  'next' and 'maint'.
+* Usually, it is best to run again latest stable versions of Autoconf,
+  Libtool, etc., since that is what most users will do. Sometimes it may
+  be necessary to use the development versions due to bugs fixed,
+  etc. Whatever is first in PATH wins.
+  (Some background: https://bugs.gnu.org/11347)
+  
+* The Automake git tree currently carries three basic branches:
+  'master', 'next' and 'maint'.  In practice, for quite a few years now,
+  as of this writing in 2023, we have been using only the master branch,
+  due to lack of time and desire to deal with anything but fixing bugs.
+  The branch information in the items below should thus be taken with a
+  large dose of salt.
 
 * The 'master' branch is where the development of the next release
   takes place.  It should be kept in a stable, almost-releasable state,
@@ -284,6 +293,12 @@
 
       <detailed list of touched files>
 
+* To choose the topic label, please review the previous commits in the
+  git log or the ChangeLog file from a release tarball. There are no
+  hard-and-fast rules; the aim is a usable description. So script
+  names, Makefile targets, and more are all viable. Some examples:
+  aclocal automake build cosmetics doc maint python release tests  ylwrap
+
 * The <detailed list of touched files> should usually be provided (but
   for short or trivial changes), and should follow the GNU guidelines
   for ChangeLog entries (described explicitly in the GNU Coding
@@ -448,7 +463,7 @@
 * Fetch new versions of the files that are maintained by the FSF by
   running "make fetch".  help2man has to be updated separately.  In case
   any file in the automake repository has been updated, commit and
-  re-run the testsuite.
+  rerun the testsuite.
 
 * Ensure that the copyright notices of the distributed files are up to
   date.  The maintainer-only target "update-copyright" can help with this.
@@ -513,7 +528,7 @@
   in by hand any "TODO" left in there.
 
 * Update version number in configure.ac to next alpha number.
-  Re-run ./bootstrap and commit.
+  Rerun ./bootstrap and commit.
 
 * Don't forget to "git push" your changes so they appear in the public
   git tree.
diff --git a/doc/automake.texi b/doc/automake.texi
index ec14c5c4c..72398adf9 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -2670,8 +2670,8 @@ installation directory.  This is typically used for 
debugging.
 
 @vindex AUTOMAKE_LIBDIR
 The environment variable @env{AUTOMAKE_LIBDIR} provides another way to
-set the directory containing Automake data files.  However
-@option{--libdir} takes precedence over it.
+set the directory containing Automake data files.  The
+@option{--libdir} option takes precedence over it.
 
 @item --print-libdir
 @opindex --print-libdir
@@ -7474,7 +7474,7 @@ be known only after @file{foo.o} has been compiled 
(@pxref{Dependencies}).
 The symptom is as follows.
 
 @example
-% make
+% @kbd{make}
 source='foo.c' object='foo.o' libtool=no \
 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
 depmode=gcc /bin/sh ./depcomp \
@@ -7509,7 +7509,7 @@ bindir.h: Makefile
 See how @file{bindir.h} gets built first:
 
 @example
-% make
+% @kbd{make}
 echo '#define bindir "/usr/local/bin"' >bindir.h
 make  all-am
 make[1]: Entering directory `/home/adl/tmp'
@@ -7526,12 +7526,12 @@ However, as said earlier, @code{BUILT_SOURCES} applies 
only to the
 if you try to run @samp{make foo} explicitly:
 
 @example
-% make clean
-rm -f bindir.h
-rm -f foo
+% @kbd{make clean}
+test -z "bindir.h" || rm -f bindir.h
+test -z "foo" || rm -f foo
 rm -f *.o
-% : > .deps/foo.Po # Suppress previously recorded dependencies
-% make foo
+% @kbd{: > .deps/foo.Po} # Suppress previously recorded dependencies
+% @kbd{make foo}
 source='foo.c' object='foo.o' libtool=no \
 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
 depmode=gcc /bin/sh ./depcomp \
@@ -8540,7 +8540,7 @@ be defined to specify additional files to clean.  These 
variables are
 @trindex maintainer-clean-local
 When cleaning involves more than deleting some hard-coded list of
 files, it is also possible to supplement the cleaning rules with your
-own commands: define a rule for any of the
+own commands.  Simply define a rule for any of the
 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
 or @code{maintainer-clean-local} targets (@pxref{Extending}).  A common
 case is deleting a directory, for instance, a directory created by the
@@ -8885,16 +8885,8 @@ example,
 AM_DISTCHECK_DVI_TARGET = pdf
 @end example
 
-To make @code{dvi} into a do-nothing target, add it to your
-@file{Makefile.am} with no commands:
-
-@example
-dvi:
-@end example
-
-@noindent
-As usual with Automake, your user-defined target will override
-Automake's target (@pxref{Extending}).
+To make @code{dvi} into a do-nothing target, see the example for
+@code{EMPTY_AUTOMAKE_TARGETS} in @ref{Third-Party Makefiles}.
 
 @trindex distcheck-hook
 @subheading distcheck-hook
@@ -9894,7 +9886,7 @@ The @file{.trs} file is used to register some metadata 
through the use
 of custom reStructuredText fields.  This metadata is expected to be
 employed in various ways by the parallel test harness; for example, to
 count the test results when printing the testsuite summary, or to decide
-which tests to re-run upon @command{make recheck}.  Unrecognized metadata
+which tests to rerun upon @command{make recheck}.  Unrecognized metadata
 in a @file{.trs} file is currently ignored by the harness, but this might
 change in the future. The list of currently recognized metadata follows.
 
@@ -9972,7 +9964,7 @@ following lines:
 @end example
 
 @noindent
-Then the corresponding test script will be re-run by @command{make check},
+Then the corresponding test script will be rerun by @command{make check},
 will contribute with @emph{five} test results to the testsuite summary
 (three of these tests being successful, one failed, and one skipped), and
 the content of the corresponding @file{.log} file will @emph{not} be
@@ -11324,7 +11316,7 @@ gcc -Wall -o foo main.o func.o
 
 @i{Clean up, so that we can rebuild everything from scratch.}
 % @kbd{make clean}
-rm -f foo
+test -z "foo" || rm -f foo
 rm -f *.o
 
 @i{Silent rules enabled: the output is minimal but informative.  In
@@ -11517,17 +11509,17 @@ As far as rules are concerned, a user-defined rule 
overrides any
 @cindex overriding semantics
 @cindex rules, overriding
 
-These overriding semantics make it possible to fine-tune some default
+These overriding semantics make it possible to fine tune some default
 settings of Automake, or replace some of its rules.  Overriding
 Automake rules is often inadvisable, particularly in the topmost
 directory of a package with subdirectories.  The @option{-Woverride}
-option (@pxref{automake Invocation}) comes in handy to catch definitions
-overridden by accident.
+option (@pxref{automake Invocation}) comes in handy to catch overridden
+definitions.
 
-Automake does not make any distinction between rules with commands and
-rules that only specify dependencies.  So it is not possible to append
-new dependencies to an @command{automake}-defined target without
-redefining the entire rule.
+Note that Automake does not make any distinction between rules with
+commands and rules that only specify dependencies.  So it is not
+possible to append new dependencies to an @command{automake}-defined
+target without redefining the entire rule.
 
 @cindex @option{-local} targets
 @cindex local targets
@@ -11762,7 +11754,7 @@ Usually, many of these rules are irrelevant to the 
third-party
 subproject, but they are required for the whole package to work.  It's
 OK to have a rule that does nothing, so if you are integrating a
 third-party project with no documentation or tag support, you could
-simply augment its @file{Makefile} as follows:
+augment its @file{Makefile} as follows:
 
 @vindex EMPTY_AUTOMAKE_TARGETS
 @cindex Automake targets, no-op
@@ -11858,16 +11850,16 @@ EXTRA_DIST = subdir/Makefile subdir/program.c ...
 
 Pushing this idea to the extreme, it is also possible to ignore the
 subproject build system and build everything from this proxy
-@file{Makefile.am}.  This might sound very sensible if you need VPATH
+@file{Makefile.am}.  This might well be sensible if you need VPATH
 builds but the subproject does not support them.
 
 @node Distributing
 @chapter Distributing @file{Makefile.in}s
 
 Automake places no restrictions on the distribution of the resulting
-@file{Makefile.in}s.  We still encourage software authors to
-distribute their work under terms like those of the GPL, but doing so
-is not required to use Automake.
+@file{Makefile.in}s.  We encourage software authors to distribute
+their work under terms like those of the GPL, but doing so is not
+required to use Automake.
 
 Some of the files that can be automatically installed via the
 @option{--add-missing} switch do fall under the GPL@.  However, these also