Re: VPATH / English / etc updates for Autoconf manual

[Ralf Wildenhues]

Hello Paul,

* Paul Eggert wrote on Wed, Jun 14, 2006 at 07:11:02AM CEST:
> That reminds me, I said I found some VPATH bugs in the Autoconf
> manual.  I eventually gave up looking for them systematically, but I
> might as well install fixes for what I found.  This was part of a
> general rewrite to fix lots of minor problems (mostly English stuff).
> Sorry for merging it into one huge glom but it is only documentation
> after all (:-), and I hope nothing in this change should be
> controversial technically.

Thank you for doing this work!

Find inline some nits.  Globally, I was wondering if we could
unify the spelling of
  timestamp  vs.  time stamp
  side-effect vs. side effect

where currently both spellings are used in the manual
(and I am unsure which should be preferred).

Cheers,
Ralf

> Here's what I installed:

> --- doc/autoconf.texi 8 Jun 2006 17:25:10 -0000       1.1042
> +++ doc/autoconf.texi 14 Jun 2006 05:08:20 -0000      1.1043

> @@ -478,7 +479,31 @@ Portable Shell Programming
>  * Special Shell Variables::     Variables you should not change
>  * Limitations of Builtins::     Portable use of not so portable /bin/sh
>  * Limitations of Usual Tools::  Portable use of portable tools
> -* Limitations of Make::         Portable Makefiles
> +
> +Portable Make Programming
> +
> +* $< in Ordinary Make Rules::   $< in ordinary rules
> +* Failure in Make Rules::       Failing portably in rules
> +* Leading _ in Macro Names::    $(_FOO) on ancient hosts
> +* Backslash-Newline-Newline::   Empty last lines in macro definitions
> +* Backslash-Newline Comments::  Spanning comments across line boundaries
> +* Long Lines in Makefiles::     Line length limitations
> +* Macros and Submakes::         @code{make macro=value} and submakes
> +* The Make Macro SHELL::        @code{$(SHELL)} portability issues
> +* Comments in Make Rules::      Other problems with Make comments
> +* obj/ and Make::               Don't name a subdirectory @file{obj}
> +* make -k Status::              Exit status of @samp{make -k}
> +* VPATH and Make::              @code{VPATH} and its many discontents

I didn't know the word discontent.  Looking it up turned up
a description that makes me wonder if it fits a technical
manual...

> @@ -1394,7 +1419,7 @@ disable warnings falling into @var{categ
>  
>  Warnings about @samp{syntax} are enabled by default, and the environment
>  variable @env{WARNINGS}, a comma separated list of categories, is
> -honored as well.  Passing @option{-W @var{category}} will actually behave as 
> if
> +honored as well.  Passing @option{-W @var{category}} actually behave as if

behaves

>  you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
>  you want to disable the defaults and @env{WARNINGS}, but (for example)
>  enable the warnings about obsolete constructs, you would use @option{-W


> @@ -2098,14 +2123,14 @@ Make @code{AC_OUTPUT} create each @file{
>  file (by default @address@hidden), substituting the output variable
>  values.
>  @c Before we used to have this feature, which was later rejected
> address@hidden because it complicates the write of Makefiles:
> address@hidden because it complicates the write of makefiles:

the writing

>  @c If the file would be unchanged, it is left untouched, to preserve
>  @c timestamp.


> @@ -2366,8 +2391,8 @@ Absolute name of @code{top_srcdir}.
>  @cindex Installation directories
>  @cindex Directories, installation
>  
> -The following variables specify the directories where the package will
> -be installed, see @ref{Directory Variables, , Variables for
> +The following variables specify the directories where the package
> +is installed, see @ref{Directory Variables, , Variables for
>  Installation Directories, standards, The @acronym{GNU} Coding
>  Standards}, for more information.  See the end of this section for
>  details on when and how to use these variables.

This change seems misleading to me.  Users may wonder whether it deals
with some already-installed files, or whether it is somehow necessary
to have something installed prior to using these variables.  IMVHO the
original wording was just fine, and I think this is one of the places
where it is very helpful to have the tense imply the actual sequence of
actions.

(With other packages, for example Libtool, it is sometimes of paramount
importance to differentiate between prior already-installed and
to-be-installed files; by analogy, changing the Libtool manual in this
way would actually remove useful information.)


> @@ -3706,10 +3737,10 @@ types are equal, then it is also searche
>  As noted in @ref{Specifying Names, , Specifying the system type}, the
>  target is rarely specified, because most of the time it is the same
>  as the host: it is the type of system for which any compiler tools in
> -the package will produce code.  What this macro will look for is,
> +the package produce code.  What this macro looks for is,

produces

>  for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
>  compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
> -will use to produce objects, archives or executables}.
> +uses to produce objects, archives or executables}.


> @@ -3835,21 +3866,21 @@ the @var{library} argument.
>  @var{action-if-found} is a list of shell commands to run if the link
>  with the library succeeds; @var{action-if-not-found} is a list of shell
>  commands to run if the link fails.  If @var{action-if-found} is not
> -specified, the default action will prepend @address@hidden to
> address@hidden and define @address@hidden (in all
> +specified, the default action prepends @address@hidden to
> address@hidden and defines @address@hidden (in all
>  capitals).  This macro is intended to support building @code{LIBS} in
>  a right-to-left (least-dependent to most-dependent) fashion such that
>  library dependencies are satisfied as a natural side-effect of
> -consecutive tests.  Some linkers are very sensitive to library ordering
> +consecutive tests.  Some linkers are sensitive to library ordering

This isn't correct, by the way.  All linkers are sensitive to library
ordering.  And while ordering issues usually only show up when someone
links statically, it is present in the common shared linking case as
well, as it, for example, defines the partial order in which the
breadth-first loading of dependent libraries is done by an ELF loader.
This, again, is of importance as soon as you start playing games with
several libraries that define/override the same dynamic symbol.


> @@ -7371,8 +7402,8 @@ avoid ``shortcuts'' and simplifications.
>  
>  Don't just play with the preprocessor if you want to prepare a
>  compilation.  For instance, using @command{cpp} to check whether a header is
> -functional might let your @command{configure} accept a header which will
> -cause some @emph{compiler} error.  Do not hesitate checking header with
> +functional might let your @command{configure} accept a header which
> +causes some @emph{compiler} error.  Do not hesitate checking a header with
>  other headers included before, especially required headers.
>  
>  Make sure the symbols you use are properly defined, i.e., refrain for

Do not hesitate to check...?


> @@ -8185,7 +8216,7 @@ which, unfortunately, is what most users
>  We emphasize that it is the @emph{initial} value of @var{variable} which
>  is saved, not that found during the execution of @command{configure}.
>  Indeed, specifying @samp{./configure FOO=foo} and letting
> address@hidden/configure} guess that @code{FOO} is @code{foo} can be two very
> address@hidden/configure} guess that @code{FOO} is @code{foo} can be two
>  different runs.
>  
>  @item

Erm, can be two different things?

> @@ -8314,7 +8345,7 @@ AC_DEFUN([AC_SHELL_TRUE],
>  
>  @noindent
>  This fails if the cache is enabled: the second time this macro is run,
> address@hidden @emph{will not be defined}.  The proper implementation
> address@hidden @emph{is not defined}.  The proper implementation
>  is:
>  
>  @example

This is another misleading statement, that is IMVHO much clearer with
future tense.


> @@ -9863,8 +9894,8 @@ AS_IF([test "$foo" = yes], [HANDLE_FOO([
>  @end example
>  
>  @noindent
> -will make sure any @code{AC_REQUIRE}'s macros of @code{HANDLE_FOO} will
> -be expanded before the first test.
> +ensures any @code{AC_REQUIRE}'s macros of @code{HANDLE_FOO}
> +are expanded before the first test.
>  @end defmac
>  
>  @defmac AS_MKDIR_P (@var{file-name})

ensures any macros @code{AC_REQUIRE}'d by @code{HANDLE_FOO}
(or some other reformulation that avoids the "'d").


> @@ -11532,7 +11562,7 @@ brace, use:
>  
>  @item
>  If the default value contains no closing brace, has to be expanded, and
> -the variable being initialized will never be IFS-split (i.e., it's not a
> +the variable being initialized is never IFS-split (i.e., it's not a
>  list), then use:
>  
>  @example
> @@ -11541,7 +11571,7 @@ list), then use:
>  
>  @item
>  If the default value contains no closing brace, has to be expanded, and
> -the variable being initialized will be IFS-split (i.e., it's a list),
> +the variable being initialized is IFS-split (i.e., it's a list),
>  then use:
>  
>  @example

These two also benefit tremendously from future tense, IMO.
The point here is that the IFS-splitting comes later in some
not-discussed part of the script.  Your change leaves me wondering
whether there is some IFS splittling involved in the currently
discussed statement.  What's complicating things even more,
IFS splitting in this current statement *is* of importance, even
though it's not what the sentence is discussing.


> @@ -12289,9 +12319,9 @@ fi
>  @c ------------------
>  @prindex @command{printf}
>  A format string starting with a @samp{-} can cause problems.
> -Bash (e.g., 2.05b) will interpret it as an options string and
> +Bash (e.g., 2.05b) interpret it as an options argument and
>  give an error.  And @samp{--} to mark the end of options is not good
> -in the address@hidden Almquist shell (e.g., 0.4.6) which will take that
> +in the address@hidden Almquist shell (e.g., 0.4.6) which takes that
>  literally as the format string.  Putting the @samp{-} in a @samp{%c}
>  or @samp{%s} is probably the easiest way to avoid doubt,
>  

interprets, gives.


> @@ -12601,8 +12631,8 @@ funny side effect: when asked whether @c
>  than @command{true} Alexandre Oliva answered:
>  
>  @quotation
> -In a sense, yes, because if it doesn't exist, the shell will produce an
> -exit status of failure, which is correct for @command{false}, but not
> +In a sense, yes, because if it doesn't exist, the shell exits
> +with a failure status, which is correct for @command{false}, but not
>  for @command{true}.
>  @end quotation
>  

This is a quotation.


> @@ -14403,7 +14493,7 @@ platforms.
>  
>  Several standards have been developed to help make your programs more
>  portable.  If you write programs with these standards in mind, you can
> -have greater confidence that your programs will work on a wide variety
> +have greater confidence that your programs work on a wide variety
>  of systems.  @xref{Standards, , Language Standards Supported by GCC,
>  gcc, Using the GNU Compiler Collection (GCC)}, for a list of C-related
>  standards.  Many programs also assume the

works


> @@ -18242,7 +18332,7 @@ then let there be address@hidden
>  In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
>  Free Software Foundation.  As they were ported to more platforms and
>  more programs were added, the number of @option{-D} options that users
> -had to select in the @file{Makefile} (around 20) became burdensome.
> +had to select in @file{Makefile} (around 20) became burdensome.
>  Especially for me---I had to test each new release on a bunch of
>  different systems.  So I wrote a little shell script to guess some of
>  the correct settings for the fileutils package, and released it as part

Erm, in alignment with your other changes, shouldn't this have been
| had to select in the makefile [...]

instead (for a moment ignoring that this and the next change are in
prosaic text written by someone, I presume David?)?

> @@ -18298,7 +18388,7 @@ which I find quite inconvenient; I didn'
>  some features (such as library functions); I didn't know that it was
>  still being maintained, and the @command{Configure} scripts I had
>  seen didn't work on many modern systems (such as System V R4 and NeXT);
> -it wasn't very flexible in what it could do in response to a feature's
> +it wasn't flexible in what it could do in response to a feature's
>  presence or absence; I found it confusing to learn; and it was too big
>  and complex for my needs (I didn't realize then how much Autoconf would
>  eventually have to grow).