[automake-commit] branch master updated: doc: omit "really" from manual.

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

The following commit(s) were added to refs/heads/master by this push:
     new e7724fb  doc: omit "really" from manual.
e7724fb is described below

commit e7724fb1b7b97f662caf154414e6f71ffcbd966c
Author: Karl Berry <karl@freefriends.org>
AuthorDate: Tue Jun 8 17:58:10 2021 -0700

    doc: omit "really" from manual.
    
    * doc/automake.texi: remove or replace "really".
---
 doc/automake.texi | 136 +++++++++++++++++++++++++++---------------------------
 1 file changed, 67 insertions(+), 69 deletions(-)

diff --git a/doc/automake.texi b/doc/automake.texi
index f73a588..351b0a1 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -1666,7 +1666,7 @@ is an excerpt of @file{config.h} after 
@command{configure} has run:
 
 As you probably noticed, @file{src/main.c} includes @file{config.h} so
 it can use @code{PACKAGE_STRING}.  In a real-world project,
-@file{config.h} can grow really big, with one @samp{#define} per
+@file{config.h} can grow quite large, with one @samp{#define} per
 feature probed on the system.
 
 The @code{AC_CONFIG_FILES} macro declares the list of files that
@@ -1990,9 +1990,10 @@ Currently, @option{--gnits} does all the checks that
 
 @itemize @bullet
 @item
-@samp{make installcheck} will check to make sure that the @option{--help}
-and @option{--version} really print a usage message and a version string,
-respectively.  This is the @option{std-options} option (@pxref{Options}).
+@samp{make installcheck} will check to make sure that the
+@option{--help} and @option{--version} print a usage message and a
+version string, respectively.  This is the @option{std-options} option
+(@pxref{Options}).
 
 @item
 @samp{make dist} will check to make sure the @file{NEWS} file has been
@@ -2096,10 +2097,10 @@ Note that the common @samp{dir} suffix is left off when 
constructing the
 variable names; thus one writes @samp{bin_PROGRAMS} and not
 @samp{bindir_PROGRAMS}.
 
-Not every sort of object can be installed in every directory.  Automake
-will flag those attempts it finds in error (but see below how to override
-the check if you really need to).
-Automake will also diagnose obvious misspellings in directory names.
+Not every sort of object can be installed in every directory.
+Automake will flag those attempts it finds in error (but see below how
+to override the check if you need to).  Automake will also diagnose
+obvious misspellings in directory names.
 
 @cindex Extending list of installation directories
 @cindex Installation directories, extending list
@@ -2123,8 +2124,8 @@ xml_DATA = file.xml
 
 This feature can also be used to override the sanity checks Automake
 performs to diagnose suspicious directory/primary couples (in the
-unlikely case these checks are undesirable, and you really know what
-you're doing).  For example, Automake would error out on this input:
+unlikely case that you need to omit these checks).  For example,
+Automake would error out on this input:
 
 @c Should be tested in primary-prefix-invalid-couples.sh
 @example
@@ -3292,9 +3293,9 @@ using @file{acinclude.m4} in new packages (@pxref{Local 
Macros}).
 While computing @file{aclocal.m4}, @command{aclocal} runs
 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
 autoconf, The Autoconf Manual}) in order to trace the macros that are
-really used, and omit from @file{aclocal.m4} all macros that are
-mentioned but otherwise unexpanded (this can happen when a macro is
-called conditionally).  @command{autom4te} is expected to be in the
+used, and omit from @file{aclocal.m4} all macros that are mentioned
+but otherwise unexpanded (this can happen when a macro is called
+conditionally).  @command{autom4te} is expected to be in the
 @env{PATH}, just as @command{autoconf}.  Its location can be
 overridden using the @env{AUTOM4TE} environment variable.
 
@@ -3369,8 +3370,8 @@ search path (@pxref{Serials}).
 
 @item --force
 @opindex --force
-Always overwrite the output file.  The default is to overwrite the output
-file only when really needed, i.e., when its contents change or if one
+Always overwrite the output file.  The default is to overwrite the
+output file only when needed, i.e., when its contents change or if one
 of its dependencies is younger.
 
 This option forces the update of @file{aclocal.m4} (or the file
@@ -3649,16 +3650,16 @@ defined macro, not at the beginning of the file.
 @acindex AC_DEFUN
 @acindex AC_PREREQ
 
-Starting with Automake 1.8, @command{aclocal} will warn about all
-underquoted calls to @code{AC_DEFUN}.  We realize this will annoy a
-lot of people, because @command{aclocal} was not so strict in the past
-and many third party macros are underquoted; and we have to apologize
-for this temporary inconvenience.  The reason we have to be stricter
-is that a future implementation of @command{aclocal} (@pxref{Future of
+Starting with Automake 1.8, @command{aclocal} warns about all
+underquoted calls to @code{AC_DEFUN}.  We realize this annoys some
+people, because @command{aclocal} was not so strict in the past and
+many third party macros are underquoted; and we have to apologize for
+this temporary inconvenience.  The reason we have to be stricter is
+that a future implementation of @command{aclocal} (@pxref{Future of
 aclocal}) will have to temporarily include all of these third party
-@file{.m4} files, maybe several times, including even files that are
-not actually needed.  Doing so should alleviate many problems of the
-current implementation; however it requires a stricter style from the
+@file{.m4} files, maybe several times, even including files that end
+up not being needed.  Doing so should alleviate many problems of the
+current implementation; however, it requires a stricter style from
 macro authors.  Hopefully it is easy to revise the existing macros.
 For instance,
 
@@ -3943,12 +3944,11 @@ macros you want to revert, and run @samp{aclocal 
--install}.
 @subsection The Future of @command{aclocal}
 @cindex @command{aclocal}'s scheduled death
 
-@command{aclocal} is expected to disappear.  This feature really
-should not be offered by Automake.  Automake should focus on
-generating @file{Makefile}s; dealing with M4 macros really is
-Autoconf's job.  The fact that some people install Automake just to use
-@command{aclocal}, but do not use @command{automake} otherwise is an
-indication of how that feature is misplaced.
+Ideally, @command{aclocal} should not be part of Automake.  Automake
+should focus on generating @file{Makefile}s; dealing with M4 macros is
+more Autoconf's job.  The fact that some people install Automake just
+to use @command{aclocal}, but do not use @command{automake} otherwise
+is an indication of how that feature is misplaced.
 
 The new implementation will probably be done slightly differently.
 For instance, it could enforce the @file{m4/}-style layout discussed in
@@ -3983,8 +3983,8 @@ For the time being, third-party packages should continue 
to install
 public macros into @file{/usr/share/aclocal/}.  If @command{aclocal}
 is replaced by another tool it might make sense to rename the
 directory, but supporting @file{/usr/share/aclocal/} for backward
-compatibility should be really easy provided all macros are properly
-written (@pxref{Extending aclocal}).
+compatibility should be easy provided all macros are properly written
+(@pxref{Extending aclocal}).
 
 
 
@@ -5676,8 +5676,8 @@ libfoo_la_SOURCES = foo.c @dots{}
 @noindent
 (In this trivial case the issue could be avoided by linking
 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
-@code{prog_SOURCES}.  But let's assume we really want to keep
-@file{prog} and @file{libfoo.la} separate.)
+@code{prog_SOURCES}.  But let's assume we want to keep @file{prog} and
+@file{libfoo.la} separate.)
 
 Technically, it means that we should build @file{foo.$(OBJEXT)} for
 @file{prog}, and @file{foo.lo} for @file{libfoo.la}.  The problem is
@@ -7532,11 +7532,10 @@ bindir.h: Makefile
 You don't have to list @emph{all} the dependencies of @file{foo.o}
 explicitly, only those that might need to be built.  If a dependency
 already exists, it will not hinder the first compilation and will be
-recorded by the normal dependency tracking code.  (Note that after
-this first compilation the dependency tracking code will also have
-recorded the dependency between @file{foo.o} and
-@file{bindir.h}, so our explicit dependency is really useful to
-the first build only.)
+recorded by the normal dependency tracking code.  (After this first
+compilation, the dependency tracking code will also have recorded the
+dependency between @file{foo.o} and @file{bindir.h}, so our explicit
+dependency is only useful to the first build.)
 
 Adding explicit dependencies like this can be a bit dangerous if you are
 not careful enough.  This is due to the way Automake tries not to
@@ -8990,7 +8989,7 @@ be considered passed nor failed; instead, they are 
@emph{skipped},
 that is, they are not run, or their result is in any case ignored for
 what concerns the count of failures and successes.  Skips are usually
 explicitly reported though, so that the user will be aware that not
-all of the testsuite has really run.
+all of the testsuite has been run.
 
 @cindex xfail
 @cindex expected failure
@@ -9255,9 +9254,9 @@ provides a more elegant way to achieve the same effect, 
with the further
 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
 (@pxref{Parallel Test Harness}).
 
-Another, less serious limitation of the serial harness is that it doesn't
-really distinguish between simple failures and hard errors; this is
-due to historical reasons only, and might be fixed in future Automake
+Another, less serious limitation of the serial harness is that it
+doesn't distinguish between simple failures and hard errors; this is
+for historical reasons, and might be fixed in future Automake
 versions.
 
 @node Parallel Test Harness
@@ -9588,8 +9587,8 @@ On the other hand, the exact semantics of how (and if) 
testsuite output
 colorization, @code{XFAIL_TESTS}, and hard errors are supported and
 handled is left to the individual test drivers.
 
-@c TODO: We should really add a working example in the doc/ directory,
-@c TODO: and reference if from here.
+@c TODO: We should add a working example in the doc/ directory,
+@c TODO: and reference it from here.
 
 @node Declaring Custom Test Drivers
 @subsection Declaring Custom Test Drivers
@@ -9614,7 +9613,7 @@ are @emph{not} a substitute for the @code{LOG_COMPILER} 
variables: the
 two sets of variables can, and often do, usefully and legitimately
 coexist.
 
-@c TODO: We should really be able to point to a clarifying example here!
+@c TODO: We should point to a clarifying example here!
 
 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
@@ -11188,9 +11187,9 @@ enable them explicitly at either @command{configure} 
run time or at
 it provides the casual user with enough information to prepare a good
 bug report in case anything breaks.
 
-Still, notwithstanding the rationales above, a developer who really
-wants to make silent rules enabled by default in his own package can
-do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
+Still, notwithstanding the rationales above, developers who wants to
+make silent rules enabled by default in their own packages can do so
+by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
 
 @c Keep in sync with silent-configsite.sh
 Users who prefer to have silent rules enabled by default can edit their
@@ -11198,7 +11197,7 @@ Users who prefer to have silent rules enabled by 
default can edit their
 default to @samp{yes}.  This should still allow disabling silent rules
 at @command{configure} time and at @command{make} time.
 
-@c FIXME: there's really a need to specify this explicitly?
+@c FIXME: is there a need to specify this explicitly?
 For portability to different @command{make} implementations, package authors
 are advised to not set the variable @code{V} inside the @file{Makefile.am}
 file, to allow the user to override the value for subdirectories as well.
@@ -12132,9 +12131,9 @@ e.g., NetBSD @command{make} will not expand globs such 
as @samp{*} in
 prerequisites of a target.
 
 @item
-Finally, it's really hard to @emph{forget} to add a file to
-@file{Makefile.am}: files that are not listed in @file{Makefile.am} are
-not compiled or installed, so you can't even test them.
+Finally, it's quite hard to @emph{forget} to add a file to
+@file{Makefile.am}: files that are not listed in @file{Makefile.am}
+are not compiled or installed, so you can't even test them.
 @end itemize
 
 Still, these are philosophical objections, and as such you may disagree,
@@ -12253,7 +12252,7 @@ package (@pxref{VPATH Builds}), and then call 
@samp{make distclean}.
 Files left in the build directory after @samp{make distclean} has run
 are listed after this error.
 
-This diagnostic really covers two kinds of errors:
+This diagnostic covers two kinds of errors:
 
 @itemize @bullet
 @item
@@ -12547,9 +12546,9 @@ You should not add options to these user variables 
within
 to modify these variables to perform a test, but you should reset
 their values afterwards.  In contrast, it is OK to modify the
 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
-them, but it is rather rare that you need to do this, unless you
-really want to change the default definitions of the @samp{AM_}
-variables in all @file{Makefile}s.
+them, but it is rather rare that you need to do this, unless you want
+to change the default definitions of the @samp{AM_} variables in all
+@file{Makefile}s.
 
 What we recommend is that you define extra flags in separate
 variables.  For instance, you may write an Autoconf macro that computes
@@ -12756,9 +12755,9 @@ data.c data.h: data.foo
 @end example
 
 @noindent
-What the above rule really says is that @file{data.c} and
-@file{data.h} each depend on @file{data.foo}, and can each be built by
-running @samp{foo data.foo}.  In other words it is equivalent to:
+What the above rule says is that @file{data.c} and @file{data.h} each
+depend on @file{data.foo}, and can each be built by running @samp{foo
+data.foo}.  In other words it is equivalent to:
 
 @example
 # We do not want this.
@@ -13092,12 +13091,11 @@ directory in @file{configure}, but if I install files 
therein,
 
 These two setups share their symptoms: @samp{make distcheck} fails
 because they are installing files to hard-coded paths.  In the latter
-case the path is not really hard-coded in the package, but we can
-consider it to be hard-coded in the system (or in whichever tool that
-supplies the path).  As long as the path does not use any of the
-standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
-@samp{$(datadir)}, etc.), the effect will be the same:
-user-installations are impossible.
+case the path is not hard-coded in the package, but we can consider it
+to be hard-coded in the system (or in whichever tool that supplies the
+path).  As long as the path does not use any of the standard directory
+variables (@samp{$(prefix)}, @samp{$(bindir)}, @samp{$(datadir)},
+etc.), the effect will be the same: user-installations are impossible.
 
 As a (non-root) user who wants to install a package, you usually have no
 right to install anything in @file{/usr} or @file{/usr/local}.  So you
@@ -13197,8 +13195,8 @@ the search path of emacs, and then substitutes 
@samp{$@{libdir@}} or
 @samp{$@{datadir@}} appropriately.
 
 The emacs case looks complicated because it processes a list and
-expects two possible layouts; otherwise it's easy, and the benefits for
-non-root users are really worth the extra @command{sed} invocation.
+expects two possible layouts; otherwise it's easy, and the benefits
+for non-root users are worth the extra @command{sed} invocation.
 
 
 @node Debugging Make Rules
@@ -13221,7 +13219,7 @@ of silent rules (@pxref{Automake Silent Rules}), you 
can use
 
 @item
 @code{make -n} can help show what would be done without actually doing
-it.  However, this will @emph{still execute} commands prefixed with
+it.  However, this @emph{still executes} commands prefixed with
 @samp{+}, and, when using GNU @command{make}, commands that contain
 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
 Execution,,, make, The GNU Make Manual}).  Typically, this is helpful