missing: do not touch timestamps; only warn for out-of-date files

missing: do not touch timestamps; only warn for out-of-date files

Before this change, the missing script had a twofold role:

  - it warned the user if some required maintainer tools was missing,
    or too old;

  - in such a case, it tried to "fix" the timestamp of the files that
    should have been rebuilt by that tool (without actually updating
    the file contents, of course), to allow the build to continue.

The second capability used to be quite useful in the days when most
projects committed files generated by maintainer-only tools in their
VCS repository (today the trend is not to keep such generated files
VCS-committed anymore).  In such a setup, the "timestamp-fixing"
capability of 'missing' was quite useful, in that it allowed users
lacking some required maintainer tool to build from a VCS checkout
in the face of skewed timestamps (as could have been caused by
"cvs update" or "git checkout").

But then, when the automatic remake rules kicked in due to the
generated files being *actually out-of-date* (e.g., because the user
had modified 'configure.ac' but lacked a modern-enough autoconf to
rebuild it), that behaviour of 'missing' caused the same problem that
plagued AM_MAINTAINER_MODE; i.e., the user would get non-dependable
builds and inconsistent statuses of the build tree -- changes to
source files don't reflect on generated files, and this can be very
confusing and cause hard-to-spot errors).

So we now believe that the best approach to deal with timestamp-related
issues is not to have 'missing' to "automagically" try to resolve
them (with all the risk and brittleness entailed), but rather to
suggest those projects still keeping generated files committed in their
VCS to provide a proper (say) 'fix-timestamp.sh' script that touches
the timestamp of the checked-out files, to ensure no spurious rebuild
will be triggered.  As a bonus, such a script can be more aware of the
particularities, nooks and corner cases of a project, and thus more
reliable than the old 'missing' script.

An example of this approach is offered by GNU awk (release 4.0.1, Git
tag 'gawk-4.0.1', commit b85b04e8).  The GNU awk maintainers commit
the Autotools-generated files (configure, Makefile.in, etc.) and other
generated in the project's Git repository, but offer a useful script
'bootstrap.sh' that fixes the timestamps of those files, to ensure no
useless remake is triggered in a freshly cloned repository:

    #! /bin/sh
    # bootstrap.sh --- touch relevant files to avoid out-of-date issues
    #                  in Git sandboxes
    touch aclocal.m4
    find awklib -type f -print | xargs touch
    sleep 1
    touch configure
    sleep 2
    touch configh.in
    sleep 1
    touch test/Maketests
    find . -name Makefile.in -print | xargs touch
    touch doc/*.info
    touch po/*.gmo
    touch po/stamp-po
    touch awkgram.c
    touch command.c
    touch version.c

A similar, simplified script is also reported as an example in the
manual.

* NEWS: Update.
* doc/automake.texi (Auxiliary Programs, maintainer-mod): Update.
(CVS): Do not suggest that 'missing' can "automagically" fix botched
timestamp due to a "cvs update"; this isn't true anymore.  Give an
example of a custom 'fix-timestamp.sh' script that can be used to
obtain the same effect (in a slightly more laborious but also more
explicit and less brittle way).  Fix some minor typos and improper
wordings while we are at it.
* lib/missing: Basically rewritten to implement the new semantics.
As a side effect (one of the several), the '--run' option is no more
required nor recognized.
* m4/missing.m4 (AM_MISSING_HAS_RUN): Enhance the test on '$MISSING'
to ensure it actually provides the new semantics (by trying the new
"witness" option '--is-lightweight').
* lib/am/distdir.am (distdir): No need anymore to check for "bad"
distributed man pages that were actually dummy stubs generated by
the 'missing' script.
* t/missing4.sh: Rename ...
* t/remake-aclocal-version-mismatch.sh: ... like this.
* t/missing2.sh: Rename ...
* t/missing-version-mismatch.sh: ... like this, and adjust to the
new semantics.
* t/missing3.sh: Adjust to the new semantics.
* t/man4.sh: Remove as obsolete.
* t/missing.sh: Likewise.
* t/missing5.sh: Likewise.
* t/txinfo30.sh: Likewise.
* t/man6.sh: Adjust grepping checks.
* t/remake6.sh: Likewise.
* t/list-of-tests.mk: Adjust.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>