Generate manpages directly from source code.

We generate manpages for autoconf’s installed programs (autoconf,
autoheader, etc.) using help2man, which runs each program in order to
learn its --help output.  Each manpage therefore has a dependency on
the existence of the corresponding program, but this dependency is
intentionally left out of the Makefile so that one can build from a
tarball release (which will include prebuilt manpages) without having
help2man installed.

But when building from a git checkout with high levels of
parallelism (-j20 or so), the missing dependency can lead to build
failures, because help2man will try to run the program before it
exists.  In an earlier patch I tried to work around this with a
recursive make invocation in the ‘.x.1’ rule, to ensure the existence
of the program.  That only traded one concurrency bug for another, now
we could have two jobs trying to build the same program simultaneously
and they would clobber each other’s work and the build would still
fail.

Instead, this patch introduces a utility script ‘help-extract.pl’ that
reads --help and --version information directly from the source code
for each program.  This utility, wrapped appropriately for each
program, is what help2man now runs.  Usage is a little weird because
help2man doesn’t let you specify any arguments to the “executable”
that it runs, but it works, and lets us write all of the true
dependencies of each manpage into the Makefile without naming any file
that would be created during a build from a tarball.  help-extract.pl
is a Perl script, so it introduces no new build-time requirements.

A downside is that we have to make sure each of the script sources in
bin/, and also part of lib/Autom4te/ChannelDefs.pm, are parseable by
help-extract.  The most important constraints are that the text output
by --help must be defined in a global variable named ‘help’, and its
definition has to be formatted just the way these definitions are
currently formatted.  Similarly for --version.  Furthermore, only some
non-literal substitutions are possible in these texts; each has to be
explicitly supported in help-extract.pl.  The current list of supported
substitutions is $0, @PACKAGE_NAME@, @VERSION@, @RELEASE_YEAR@, and
Autom4te::ChannelDefs::usage.

The generated manpages themselves are character-for-character
identical before and after this patch.

 * build-aux/help-extract.pl: New build script that extracts --help
  and --version output from manpages.

 * man/autoconf.w, man/autoheader.w, man/autom4te.w, man/autoreconf.w
 * man/autoscan.w, man/autoupdate.w, man/ifnames.w: New shell scripts
   which wrap build-aux/help-extract.pl.

 * man/local.mk: Generate each manpage by running help2man on the
   corresponding .w script, not on the built utility itself.
   Revise all dependencies to match.

 * bin/autoconf.as: Rename ‘usage’ variable to ‘help’ and
   ‘help’ variable to ‘usage_err’.
 * bin/autoheader.in: Call Autom4te::ChannelDefs::usage with no
   function-call parentheses, matching all the other scripts.
 * bin/autom4te.in: Initialize $version with a regular double-quoted
   string, not a heredoc, matching all the other scripts.
 * bin/autoscan.in: Remove global variable $configure_scan.

4 files changed, 11 insertions, 13 deletions

diff --git a/bin/autoconf.as b/bin/autoconf.as
index ab6e3c52..ddf8cced 100644
--- a/bin/autoconf.as
+++ b/bin/autoconf.as
@@ -22,7 +22,7 @@ m4_divert_push([HEADER-COPYRIGHT])dnl
 m4_divert_pop([HEADER-COPYRIGHT])dnl back to BODY
 AS_ME_PREPARE[]dnl
 
-usage=["\
+help=["\
 Usage: $0 [OPTION]... [TEMPLATE-FILE]
 
 Generate a configuration script from a TEMPLATE-FILE if given, or
@@ -75,11 +75,11 @@ There is NO WARRANTY, to the extent permitted by law.
 
 Written by David J. MacKenzie and Akim Demaille."]
 
-help="\
+usage_err="\
 Try '$as_me --help' for more information."
 
 exit_missing_arg='
-  m4_bpatsubst([AS_ERROR([option '$[1]' requires an argument$as_nl$help])],
+  m4_bpatsubst([AS_ERROR([option '$[1]' requires an argument$as_nl$usage_err])],
     ['], ['\\''])'
 # restore font-lock: '
 
@@ -100,7 +100,7 @@ while test $# -gt 0 ; do
     --version | -V )
        echo "$version" ; exit ;;
     --help | -h )
-       AS_ECHO(["$usage"]); exit ;;
+       AS_ECHO(["$usage_err"]); exit ;;
 
     --verbose | -v )
        verbose=:
@@ -154,7 +154,7 @@ while test $# -gt 0 ; do
        break ;;
     -* )
        exec >&2
-       AS_ERROR([invalid option '$[1]'$as_nl$help]) ;;
+       AS_ERROR([invalid option '$[1]'$as_nl$usage_err]) ;;
     * )
        break ;;
   esac
@@ -178,7 +178,7 @@ case $# in
   1)
     infile=$1 ;;
   *) exec >&2
-     AS_ERROR([invalid number of arguments$as_nl$help]) ;;
+     AS_ERROR([invalid number of arguments$as_nl$usage_err]) ;;
 esac
 
 # Unless specified, the output is stdout.
diff --git a/bin/autoheader.in b/bin/autoheader.in
index b8ed9d3f..2a9a2e07 100644
--- a/bin/autoheader.in
+++ b/bin/autoheader.in
@@ -72,7 +72,7 @@ or else 'configure.in'.
   -f, --force              consider all files obsolete
   -W, --warnings=CATEGORY  report the warnings falling in CATEGORY
 
-" . Autom4te::ChannelDefs::usage () . "
+" . Autom4te::ChannelDefs::usage . "
 
 Library directories:
   -B, --prepend-include=DIR  prepend directory DIR to search path
diff --git a/bin/autom4te.in b/bin/autom4te.in
index 3a80d4b7..d98998de 100644
--- a/bin/autom4te.in
+++ b/bin/autom4te.in
@@ -204,8 +204,7 @@ General help using GNU software: <https://www.gnu.org/gethelp/>.
 
 # $VERSION
 # --------
-$version =  <<"EOF";
-autom4te (@PACKAGE_NAME@) @VERSION@
+$version = "autom4te (@PACKAGE_NAME@) @VERSION@
 Copyright (C) @RELEASE_YEAR@ Free Software Foundation, Inc.
 License GPLv3+/Autoconf: GNU GPL version 3 or later
 <https://gnu.org/licenses/gpl.html>, <https://gnu.org/licenses/exceptions.html>
@@ -213,7 +212,7 @@ This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.
 
 Written by Akim Demaille.
-EOF
+";
 
 
 ## ---------- ##
diff --git a/bin/autoscan.in b/bin/autoscan.in
index 0eb35040..9780f7db 100644
--- a/bin/autoscan.in
+++ b/bin/autoscan.in
@@ -87,7 +87,6 @@ my %needed_macros =
    'AC_PREREQ' => [$me],
   );
 
-my $configure_scan = 'configure.scan';
 my $log;
 
 # Autoconf and lib files.
@@ -103,7 +102,7 @@ $help = "Usage: $0 [OPTION]... [SRCDIR]
 Examine source files in the directory tree rooted at SRCDIR, or the
 current directory if none is given.  Search the source files for
 common portability problems, check for incompleteness of
-'configure.ac', and create a file '$configure_scan' which is a
+'configure.ac', and create a file 'configure.scan' which is a
 preliminary 'configure.ac' for that package.
 
   -h, --help          print this help, then exit
@@ -462,7 +461,7 @@ sub output_kind ($$)
     if exists $kind_comment{$kind};
   foreach my $word (sort keys %{$used{$kind}})
     {
-      # Output the needed macro invocations in $configure_scan if not
+      # Output the needed macro invocations in configure.scan if not
       # already printed, and remember these macros are needed.
       foreach my $macro (@{$macro{$kind}{$word}})
 	{