Re: Fwd: autoreconf manual entry for --force

[Eric Blake]

On 04/21/2015 01:04 AM, Emil Laine wrote:
> Hi,
> 
> autoreconf's (version 2.69) man entry for --force states:
>> consider all files obsolete

Which in turn is generated from 'autoreconf --help' output, which is
intentionally terse.

> 
> autoreconf's html manual entry for --force states:
>> Remake even configure scripts and configuration headers
>> that are newer than their input files (configure.ac and,
>> if present, aclocal.m4).
> (link: 
> http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/autoreconf-Invocation.html)

This is also the official documentation in the info pages.

> 
> When invoking autoreconf with both --install and --force
> options, it calls automake --add-missing --force-missing,
> which in turn "causes standard files to be reinstalled
> even if they already exist in the source tree" (quoted
> from automake's html manual, link:
> https://www.gnu.org/software/automake/manual/html_node/automake-Invocation.html).
> 
> I couldn't deduce this from autoreconf's manual entries,
> which led to a problem that I posted about on the Unix &
> Linux Stack Exchange site (link to post:
> http://unix.stackexchange.com/q/197238/103132).
> 
> So, IMO, the man entry for autoreconf --force is a bit
> vague, while the html manual entry for it simply doesn't
> mention all the relevant information. They don't even
> say the same thing in different ways, they just say
> something completely different.

One is supposed to be a short summary of the other.  But if you have
ideas for better wording, I'm all ears; patches are welcome to improve
either wording.

> 
> I think this could be fixed to avoid further possible
> confusion. For example the entries in automake's manuals
> are much clearer.
> 
> For example, the autoreconf entry for --install could say:
>> copy missing auxiliary and standard files if they don't
>> exist
> instead of simply:
>> copy missing auxiliary files
> 
> The autoreconf entry for --force could say something like:
>> consider all auxiliary and standard files obsolete and
>> overwrite them
> instead of just:
>> consider all files obsolete

I'll see if I can turn these wording suggestions into patch form.

> 
> IMO, this would make the consequences much more evident.

Also, have you asked on the automake list whether INSTALL should be
treated more like COPYING, by offering a way (perhaps via optional flag)
to leave a custom version intact instead of forcefully rewriting it to
the "standard" version?  It sounds like part of the confusion is not
autoconf's fault, but automake's insistence on treating '--force
--install' as bringing all files up-to-date to their newest "standard"
counterpart by forcefully undoing any customizations.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature