Re: VPATH / English / etc updates for Autoconf manual

[Ralf Wildenhues]

Hello Paul,

* Paul Eggert wrote on Thu, Jun 15, 2006 at 10:52:26AM CEST:
> Ralf Wildenhues <address@hidden> writes:
> 
> > I was wondering if we could unify the spelling of
> >   timestamp  vs.  time stamp
> >   side-effect vs. side effect
> 
> Posix uses "timestamp" and "side effect" so let's use that.

Good.

> > I didn't know the word discontent.  Looking it up turned up
> > a description that makes me wonder if it fits a technical
> > manual...
> 
> You didn't get the reference to Sigmund Freud's famous book?  Freud
> had phobias about death, trains, ferns, and VPATH (you could look it
> up :-).

:-)

> OK, let's change it to "woes".

That seems better, thanks.

> > 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.
> 
> But the actual sequence of actions might be other than what you're
> thinking of, and the code works just fine.  This is partly indicated
> by the fact that the rest of the section does not use future tense.
> 
> I kept "will" when there was a real need to refer to a future action,
> but here I think the tense is confusing more than helpful.  However,
> I'll reword it to remove "is" as well ("The following specify the
> directories for package installation...."); I hope this addresses
> at least part of the objection.

Yes, that's definitely better.

> > ensures any macros @code{AC_REQUIRE}'d by @code{HANDLE_FOO}
> > (or some other reformulation that avoids the "'d").
> 
> OK, done.  I'll also fix all instances of "}'" that look ugly in
> Emacs info mode.

Nice.

> >> -have greater confidence that your programs will work on a wide variety
> >> +have greater confidence that your programs work on a wide variety
> >> ...
> >
> > works
> 
> "programs work" looks OK to me.

Just goes to show how high my error rate is even when reviewing...

>       * doc/autoconf.texi: More formatting and English tweaks,
>       many suggested by Ralf Wildenhues.
>       Reword to avoid "@code{...}'s" and the like, since it's ugly
>       with Emacs info mode.  discontents -> woes.
>       Put a few "will"s back.  time stamp -> timestamp.
>       side-effect -> side effect.

All fine, thanks, except this one change:

--- doc/autoconf.texi   15 Jun 2006 07:33:41 -0000      1.1047
+++ doc/autoconf.texi   15 Jun 2006 08:47:21 -0000      1.1048

> @@ -11596,7 +11596,7 @@ address@hidden"$default"@}
>  If the default value contains a closing brace, then use:
>  
>  @example
> -test "address@hidden@}" = set || var='address@hidden@}'
> +test "address@hidden@}" = set || var="$default"
>  @end example
>  @end enumerate
>  

The assignment has to use a value that contains a literal closing brace.
I think you once had to explain this example to me, because I didn't
understand it.  :-)

Cheers,
Ralf