texi: info files can be generated in the builddir

User can now ask info files to be built in the $(builddir), rather than
the $(srcdir), by specifying the Automake option 'info-in-builddir'.
This feature was requested by the developers of GCC, GDB, GNU binutils
and the GNU bfd library.  See the extensive discussion about automake
bug#11034 for more details.

OK, to be honest, having '.info' files built in the builddir was
*already* possible, but only using ugly and undocumented hacks involving
definition of the CLEANFILES and/or DISTCLEANFILES.  For example, the
binutils project did something like this in the relevant 'Makefile.am':

    # Automake 1.9 will only build info files in the objdir if they are
    # mentioned in DISTCLEANFILES.  It doesn't have to be unconditional,
    # though, so we use a bogus condition.
    if GENINSRC_NEVER
    DISTCLEANFILES = binutils.info
    endif

See also the extensive discussion about automake bug#11034; in
particular, the following messages:
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#65>
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#80>
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#86>
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#101>

* lib/Automake/Options.pm (_is_valid_easy_option): Recognize the
new 'info-in-builddir' option.
* automake.in (handle_texinfo_helper): If that option is set,
initialize '$insrc' to '0', so that info files will be generated
in the builddir.  Adjust comments to match.
* t/txinfo-builddir.sh: New test.
* t/list-of-tests.mk: Add it.
* NEWS: Update.
* doc/automake.texi: Document the new options.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
texi: deprecate hack about info files in CLEANFILES variables

For quite a long time, Automake has been implementing an undocumented
hack which ensured that '.info' files which appeared to be cleaned (by
e.g. being listed in the CLEANFILES or DISTCLEANFILES variables) were
built in the builddir rather than in the srcdir; this hack was introduced
to ensure better backward-compatibility with packages such as Texinfo,
which did things like:

    info_TEXINFOS = texinfo.txi info-stnd.texi info.texi
    DISTCLEANFILES = texinfo texinfo-* info*.info*
    # Do not create info files for distribution.
    dist-info:
        @:

in order not to distribute .info files.

Now that we have the 'info-in-builddir' option that explicitly causes
generated '.info' files to be placed in the builddir, this hack should
be longer necessary, so we deprecate it with runtime warnings.  It is
scheduled to be removed altogether in Automake 1.14.

* automake.in (handle_texinfo_helper): Raise proper runtime warnings
if the hack is triggered.
* NEWS: Update.
* t/txinfo28.sh: Adjust.
* t/txinfo23.sh: Likewise.
* t/txinfo25.sh: Adjust and extend.
* t/txinfo24.sh: Likewise.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
maint: add some of my maintainer-specific scripts

They are likely not general enough for widespread use, but they
are useful nonetheless.

In the best-case scenario, they will start to be used by other
people, and thus accordingly improved and made more general and
flexible.

In the worst case scenario, well, I still get to keep them in a
centralized, blessed place, simplifying the deployment and use
of them; so still a win for me :-)

* maint/am-ft: New script.
* maint/am-xft: Likewise.
* maint/rename-tests: Likewise.
* Makefile.am (EXTRA_DIST): Add them.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
tests: more significant names for some tests

* t/spy.sh: Rename...
* t/spy-double-colon.sh: ... like this.
* t/yacc4.sh: Rename...
* t/yacc-misc.sh: ... like this.
* t/yaccdry.sh: Rename...
* t/yacc-dry.sh: ... like this.
* t/yaccpp.sh: Rename...
* t/yacc-cxx-grepping.sh: ... like this.
* t/yaccvpath.sh: Rename...
* t/yacc-vpath.sh: ... like this.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
plans: add the "PLANS" directory

Individual files or sub-directories about future and on-going
development plans in Automake will be added in follow-up commits.

This new set of documents is meant to help ensure a more controlled
and smooth development and evolution for Automake, in several ways.

 - Having the plans clearly spelled out should will avoid messy
   roadmaps with no clear way forward or with muddy or ill-defined
   aims or purposes; a trap this is too easy to fall into.

 - Keeping planned changes cooking and re-hashed for a while should
   ensure rough edges are smoothed up, transitions are planned in a
   proper way (hopefully avoiding debacles like the AM_MKDIR_PROG_P
   deprecation and the AM_CONFIG_HEADER too-abrupt removal), and
   "power users" have more chances of getting informed in due time,
   thus having all the time to prepare for the changes or raise
   objections against them.

 - Having the plans clearly stated and registered in a "centralized"
   location should make it more difficult to them to slip through
   the cracks, getting forgotten or (worse) only half-implemented.

 - Even for discussions and plans registered on the Bug Tracker
   as well, a corresponding entry in the PLANS directory can help
   in keeping main ideas summarized, and consensus and/or objections
   registered and easily compared.

Motivation:
<http://blog.flameeyes.eu/2013/01/autotools-mythbuster-automake-pains>
Not a flatting picture for us (and maybe a little too harsh), but
basically true and even spot-on in some regards.

* PLANS/README: New.
* Makefile.am (EXTRA_DIST): Distribute the whole PLANS directory.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
maint: move more maintainer files in the 'maint/' subdir

* maint.mk: Move ...
* maint/maint.mk: ... here.
* syntax-checks.mk: Move ...
* maint/syntax-checks.mk: ... here.
* Makefile.am: Adjust.
* GNUmakefile: Likewise.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
tests: move runtest.in away from the top-lever directory

Not only this leaves the top-lever directory less cluttered, but
helps in keeping the testsuite-related files more "centralized".

* runtest.in: Move ...
* t/ax/runtest.in: ... here.  While at it, add customary
'@configure_input@' comment line.
* Makefile.am (runtest, EXTRA_DIST): Adjust.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
runtest: better command line API

* t/ax/runtest.in: Accept options '-k' and '--keep-testdirs' (same
as exporting '$keep_testdirs' to "yes").  To improve compatibility
with the "make check" interface, allow environment variables to be
passes on the command line.  Minor adjustments while at it.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
Merge branch 'info-in-builddir' into maint

* info-in-builddir:
  texi: deprecate hack about info files in CLEANFILES variables
  texi: info files can be generated in the builddir

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
tests: make two new test executable

* t/backslash-issues.sh: This.
* t/extra-data.sh: And this.

Issue revealed by the 'sc_tests_executable' maintainer check.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
texi: Texinfo sources and CLEANFILES definition should co-exist peacefully

But they don't now, due to a regression introduced in commit
'v1.13.1-4-gc1a8f56'.  Fix it.  The regression was hitting our
own build system!

* automake.in (handle_texinfo_helper): Only complain if the
'info-in-builddir' is not active and a '.info' file (not any
random file!) is listed in CLEANFILES or DISTCLEANFILES.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
build: enable all warnings as fatal in our own build system

Automake should of course be able to bootstrap itself in a
warning-free manner w.r.t. the Autotools.  So make any failure
to do so fatal.  Not doing so caused the regression fixed by
previous commit 'v1.13.1-22-ga790fae' to go unnoticed.

* configure.ac (AM_INIT_AUTOMAKE): Add '-Werror' and '-Wall'.
* bootstrap.sh: Pass the '-Wall -Werror' options to aclocal,
automake and autoconf invocations.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
build: don't enable 'color-tests' automake option explicitly

It's enabled by default since commit 'v1.12.2-136-g2d5571e' (this
change appeared in Automake 1.13).

* configure.ac (AM_INIT_AUTOMAKE): Drop 'color-tests'.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
NEWS: improve wordings in entry deprecating suffix-less info files

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
texi: remove workaround for older Texinfo (4.1)

* lib/am/texibuild.am: Here, in the rules generating HTML output.
We can do so because, since Automake 1.13, we require Texinfo >= 4.9
anyway.

Basically a backport of Automake-NG commit '1.12.2-879-ge6caf5e'.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
docs: mention dist-hook help for EXTRA_DIST

* automake.texi (Basics of Distribution): mention dist-hook
as working around the problems of whole directories in EXTRA_DIST.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
Merge branch 'plans' into maint

* plans:
  plans: add the "PLANS" directory

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

Conflicts:
	Makefile.am
plans: add some on-going plans (already registered on the bug tracker)

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
Merge branch 'plans' into maint

* plans:
  plans: add some on-going plans (already registered on the bug tracker)
coverage: user can avoid distributing '.info' pages

Can be done like this:

        AUTOMAKE_OPTIONS = info-in-builddir
        dist-info:
            @:

Note that this usage is not yet documented: we might decide to go
for a fully-fledged 'no-dist-info' flag, or something like that, in
future automake version (this is not yet decided); in which case,
it's better not to have people start to rely on the hack above.
Still, there's no good reason to break it gratuitously, hence this
test coverage.

* t/txinfo-nodist-info.sh: New test.
* t/list-of-tests.mk: Add it.

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