Today it came to my attention that, if you don’t already know that all
the GNU manuals are readable in HTML format on gnu.org, it’s not easy
to find one starting from typical --help output and/or help2man-
generated manpages. Let’s do a little to make this easier, and have
“https://www.gnu.org/software/autoconf/manual/” appear prominently in
both the --help output and the trailer text of our generated manpages.
This uses the extended tmac.an “.MT” and “.UR” directives, which are
not universal, but I suspect anyone who’s actively using Autoconf on
an old system does not need the advice, and they can get it from
--help regardless.
* bin/autoconf.in, bin/autoheader.in, bin/autom4te.in, bin/autoreconf.in
* bin/autoscan.in, bin/autoupdate.in, bin/ifnames.in:
Refer specifically to https://www.gnu.org/software/autoconf/manual/
for the web version of the complete Autoconf manual.
* man/common.x: Likewise; also, suggest the Savannah tracker as
well as bug-autoconf for bug reports.
Of all the installed programs (autoconf, autoheader, autom4te,
autoreconf, autoscan, autoupdate, ifnames) autoconf is the only one
that is a shell script instead of a Perl script. This means it has to
do a lot of fiddly quoting and requoting to assemble an autom4te
command line, it doesn’t get to use the shared option handling code in
Autom4te/{General,Getopt}.pm, and it has to duplicate usage text that
properly should only be in Autom4te/ChannelDefs.pm. It also means
there’s extra code in build-aux/help-extract.pl just for it, and a
special two-phase generation process in bin/local.mk.
This also paves the way for the bootstrap script mentioned in the
previous commit; it will only have to know how to deal with
substitution variables, not generation of m4sh scripts.
The new script winds up being slightly longer on disk but that’s
because our boilerplate for Perl scripts is quite long. The code is
visibly simpler.
* bin/autoconf.as: Rename to bin/autoconf.in and rewrite in Perl.
* bin/local.mk (EXTRA_DIST): Change autoconf.as to autoconf.in.
(MOSTLYCLEANFILES): Don’t delete autoconf.in.
(bin/autoconf.in): Delete rule.
(ETAGS_PERL): Add autoconf.in and sort list.
(ETAGS_SH): Delete, no longer needed.
* tests/tools.at: Syntax-check autoconf as a Perl script.
* build-aux/help-extract.pl: Remove all code for extracting usage text
from shell scripts.
* man/autoconf.w, man/local.mk: Refer to autoconf.in, not autoconf.as.
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.
If we are doing a VPATH build and we generate the manpages,
they will be written to the build directory, and should be
deleted by ‘make distclean’; ‘make distcheck’ fails if this
is not done. However, if we are doing a build in the source
directory, the manpages might have been shipped to us and we
should *not* delete them in ‘make distclean’.
Correction to 5d3c99e562.
* man/local.mk (distclean-local-man): New rule. Delete $(dist_man_MANS)
in VPATH builds only.
(MOSTLYCLEANFILES, .x.1): Don’t use globs to decide what to delete.
It is not necessary to generate the manpages in the source directory
during a split build; ‘make dist’ can still find them in the build
directory and put them in the tarball.
Also add some defensive logic to the .x.1 rule to ensure that
bin/command and tests/command exist before generating man/command.1.
Without this, if you do a sufficiently parallel build, help2man may
generate the manpage from an older installed copy of ‘command’.
(Ideally, we wouldn’t have to run ‘command’ at all and this would not
be an issue, but ‘help2man’ doesn’t appear to support that.)
After this patch, the only files written to the source directory
during the ‘make’ phase of a split build (starting from a clean Git
checkout) are
doc/version.texi
doc/stamp-vti
doc/autoconf.info
doc/standards.info
These are not under our control, they’re being created by automake’s
built-in rules for Texinfo documentation.
* man/local.mk: Replace all instances of $(mansrcdir) with literal ‘man’.
(.x.1): Ensure that bin/command, tests/command, and the man
directory exist before creating man/command.1.
Done via 'make update-copyright', since all files are effectively
modified and distributed this year via public version control.
* all files: Update copyright year.
* Makefile.am (SUBDIRS): Remove (its last component 'man' has just
been removed).
(SUFFIXES): New, defined to empty, to be updated later by included
files.
($(srcdir)/man/local.mk): Include this.
* configure.ac (AC_CONFIG_FILES): Drop 'man/Makefile'.
* lib/freeze.mk (SUFFIXES): Extend with '+=' rather than defining
with '='.
* man/Makefile.am: Rename ...
* man/local.mk: ... like this, and adjust throughout.
Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
Done via 'make update-copyright', since all files are effectively
modified and distributed this year via public version control.
* all files: Update copyright year.
* Makefile.am (EXTRA_DIST): Distribute .version.
(.version): New rule.
* man/Makefile.am (common_dep): Depend on .version, not
configure.ac.
(.x.1): Use package name for version string.
* GNUmakefile [!_have-Makefile]: Sync from upstream, again.
* build-aux/git-version-gen: Sync from upstream.
Signed-off-by: Eric Blake <ebb9@byu.net>
* man/Makefile.am (.x.1): Now that scripts in bin/ and tests/
are guaranteed to be built, remove the rules that tried to build
them. Before, with a parallel build, these rules could lead to
two processes writing tests/wrapper.in concurrently.
* aclocal.m4: Remove.
* configure: Remove.
* Makefile.in: Remove, along with all other Makefile.in in subdirs.
* .gitignore: Add aclocal.m4, configure and Makefile.in. Sort.
* README-hacking: New file: how to build from just-checked-out sources.
Many files are renamed; all uses of their names were changed.
* .x-sc_trailing_blank: Renamed from .x-sc_trailing_blank.
* .x-sc_useless_cpp_parens: New file.
* build-aux/config.guess: Renamed from config/config.guess. Update.
* build-aux/config.sub: Renamed from config/config.sub. Update.
* build-aux/elisp-comp: Renamed from config/elisp-comp.
* build-aux/install-sh: Renamed from config/install-sh. Update.
* build-aux/mdate-sh: Renamed from config/mdate-sh.
* build-aux/missing: Renamed from config/missing.
* build-aux/texinfo.tex: Renamed from config/texinfo.tex. Update.
* build-aux/vc-list-files: Renamed from config/vc-list-files.
* config/Makefile.am: Removed.
* config/mkinstalldirs: Removed.
* config/move-if-change: Removed.
* m4/m4.m4: Renamed from config/m4.m4. Add (C) to copyright notice.
* Makefile.am (SUBDIRS): Remove config.
(ACLOCAL_AMFLAGS): Include from m4, not config.
(EXTRA_DIST): Add config/announce-gen, config/prev-version.txt.
(WGET, WGETFLAGS): New macros, since Makefile.maint no longer does this.
(autom4te-update): Rewrite with a loop. Get from gnulib, not automake.
Fail if there's an error.
* Makefile.cfg (move_if_change): Remove.
(wget_files): Remove.
(cvs_executable_files): New macro.
(cvs_files): Use it. Remove mkinstalldirs. Add fdl.texi.
(executable-update): Use $(cvs_executable_files).
(local-checks-to-skip): Remove.
* Makefile.maint: Merge from coreutils, plus add our own changes
(gzip_rsyncable): New macro.
(GZIP_ENV): Use it.
(CVS_LIST): Use build-aux/vc-list-files.
(VERSION_REGEXP): New macro.
(local-checks-available): Add patch-check, $(syntax-check-rules),
check-AUTHORS.
(syntax-check-rules): Compute dynamically.
(sc_cast_of_x_alloc_return_value): Work even if no source files.
(sc_cast_of_alloca_return_value): Likewise.
(sc_prohibit_atoi_atof): Simplify regexp.
(sc_no_if_have_config_h, sc_require_config_h):
(sc_prohibit_assert_without_use,
(sc_obsolete_symbols): Check for O_NDELAY.
(sc_texi_notab): Remove.
(sc-changelog): Don't make an exception for '----' lines.
(.re-list): Remove, so we don't have a junk file behind.
(sc_system_h_headers): Remove the need for .re-list.
(sc_the_the): New rule.
(sc_tight_scope): Simplify.
(sc_trailing_space): Renamed from sc_trailing_blank.
(longopt_re): New macro.
(sc_two_space_separator_in_usage): New rule.
(sc_unmarked_diagnostics): Look at all files under CVS.
(sc_useless_cpp_parens, patch-check, check-AUTHORS): New rules.
(news-date-check, changelog-check): Version is OK.
(po-check): Look for lib files even if not in CVS.
(copyright-check): Use $() not ``.
(maintainer-distcheck): Do not depend on changelog-check.
(my-distcheck): Depend on $(release_archive_dir)/$(prev-tgz).
Also check for -Wpointer-arith.
(WGET, WGETFLAGS, tgz-md5, tgz-sha1, bz2-md5, bz2-sha1):
(xdelta-md5, xdelta-sha1, tgz-size, bz2-size, xd-size, rel-check):
Remove.
(announcement): Add --gpg-key-id arg.
(cvs-sv): Remove.
(move_if_change): Just use mv.
(local_updates: Remove wget-update, po-update.
(po_repo, do-po-update, po-update, wget_files, get-targets): Remove.
(config.guess-url_prefix, config.sub-url_prefix): Remove.
(ansi2knr.c-url_prefix, texinfo.tex-url_prefix):
(standards.texi-url_prefix, make-stds.texi-url_prefix, target, url):
($(get-targets)): Remove.
(cvs_files): Remove missing, mkinstalldirs, ansi2knr.c.
(gnulib_repo): Renamed from automake_repo. Get from gnulib now.
(cvs-update): Get from gnulib.
(emut_upload_commands): gnupload is in build-aux now.
(alpha beta major): Add changelog-check. Check version.
* configure.ac (AC_CONFIG_AUX_DIR): Renamed from config to build-aux.
(AC_CONFIG_FILES): Remove.
* bin/autoconf.as: Add spaces to avoid distcheck warning.
* config/announce-gen: Sync from coreutils.
* doc/make-stds.texi: Sync from gnulib.
* doc/standards.texi: Likewise.
* man/Makefile.am: Adjust for config -> build-aux renaming.
* tests/Makefile.am: Prefer $(FOO) to @FOO@.
* tests/local.at: Adjust from config -> build-aux renaming.
* tests/tools.at: Likewise.
* tests/torture.at: Likewise.
