* Karl Berry wrote on Sat, Nov 29, 2008 at 12:34:40AM CET: > Check that none of the man pages contain the error message. If any > do, error out with a descriptive message. > > Ok, sounds good. > > We could also move such a check into 'distcheck'. That way 'dist' could > still work if you don't have help2man, only 'distcheck' wouldn't. > > I think it would be best for both make dist and make distcheck to fail > if help2man is not available and those spuriously-generated man pages > somehow crept in. That is the only time (making a distribution) that it > really matters!
Agreed. The following patch (against git Automake) moves the test to the `distdir' target, which is updated by both `dist' and `distcheck'. Comments appreciated (adding Werner to THANKS not shown). I'm still wondering about whether and how to document this in the manual. Some of the rationale in tests/man4.test probably belongs elsewhere. Note that the recommendation to use maintainer-clean to remove the bogus man pages requires that the package author added them to MAINTAINERCLEANFILES. I hope that is a reasonably safe assumption. Cheers, Ralf Revamp semantics for `missing help2man' and manpage distribution. Previously, `missing help2man' would create a missing man page containing an error message, and exit 1. This does not play well with `make': the next run will see this particular man page as being up to date, and will only error out on the next generated man page, if any; repeat until all pages are done. This patch changes `missing' to exit successfully in this case, but `make dist' will ensure that no such man pages are packaged. * lib/missing: Exit successfully even if we create a replacement page due to missing help2man. * automake.in (make_paragraphs): Define %HAVE-MANS% to be true if this makefile deals with man pages. * lib/am/distdir.am (distdir): If %INSTALL-MAN% and %HAVE-MANS%, check that no man page in $(MANS) contains the replacement text from `missing'. * tests/man4.test: New test. * tests/Makefile.am: Update. * NEWS: Reorder a bit, update. * THANKS: Update. Report by Werner Lemberg and Karl Berry. diff --git a/NEWS b/NEWS index 8b43c69..0eaebbd 100644 --- a/NEWS +++ b/NEWS @@ -136,8 +136,6 @@ New in 1.10a: - AM_SUBST_NOTMAKE may prevent substitution of AC_SUBSTed variables, useful especially for multi-line values. - - The `missing' script works better with versioned tool names. - - Automake's early configure-time sanity check now diagnoses an unsafe absolute source directory name and makes configure fail. @@ -165,6 +163,24 @@ Bugs fixed in 1.10a: extra quoting used internally by Autoconf 2.62 and newer (it used to work only without the `--file=' bit). + - The `missing' script works better with versioned tool names. + + - Semantics for `missing help2man' have been revamped: + + Previously, if `help2man' was not present, `missing help2man' would have + the following semantics: if some man page was out of date but present, then + a warning would be printed, but the exit status was 0. If the man page was + not present at all, then `missing' would create a replacement man page + containing an error message, and exit with a status of 2. This does not play + well with `make': the next run will see this particular man page as being up + to date, and will only error out on the next generated man page, if any; + repeat until all pages are done. This was not desirable. + + These are the new semantics: if some man page is not present, and help2man + is not either, then `missing' will warn and generate the replacement page + containing the error message, but exit successfully. However, `make dist' + will ensure that no such bogus man pages are packaged into a tarball. + * Bugs introduced by 1.10: - Fix output of dummy dependency files in presence of post-processed diff --git a/automake.in b/automake.in index 691bad3..6abc1a5 100755 --- a/automake.in +++ b/automake.in @@ -6851,6 +6851,7 @@ sub make_paragraphs ($%) 'INSTALL-INFO' => ! option 'no-installinfo', 'INSTALL-MAN' => ! option 'no-installman', + 'HAVE-MANS' => !! var ('MANS'), 'CK-NEWS' => !! option 'check-news', 'SUBDIRS' => !! var ('SUBDIRS'), diff --git a/lib/am/distdir.am b/lib/am/distdir.am index 218e65a..e72d164 100644 --- a/lib/am/distdir.am +++ b/lib/am/distdir.am @@ -80,6 +80,22 @@ if %?CK-NEWS% endif %?CK-NEWS% endif %?TOPDIR_P% ## +## `missing help2man' may have created some bogus man pages. Ensure they +## are not distributed. +## +if %?INSTALL-MAN% +if %?HAVE-MANS% + @list='$(MANS)'; if test -n "$$list" \ + && grep 'ab help2man is required to generate this page' $$list >/dev/null; then \ + echo "error: found man pages containing the \`missing help2man' replacement text:" >&2; \ + grep -l 'ab help2man is required to generate this page' $$list | sed 's/^/ /' >&2; \ + echo " to fix them, install help2man, remove and regenerate the man pages;" >&2; \ + echo " typically \`make maintainer-clean' will remove them" >&2; \ + exit 1; \ + else :; fi +endif %?HAVE-MANS% +endif %?INSTALL-MAN% +## ## Only for the top dir. ## if %?TOPDIR_P% diff --git a/lib/missing b/lib/missing index 4758c82..c6be1a0 100755 --- a/lib/missing +++ b/lib/missing @@ -1,7 +1,7 @@ #! /bin/sh # Common stub for a few missing GNU programs while installing. -scriptversion=2008-11-24.07 +scriptversion=2008-11-29.19 # Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005, 2006, # 2008 Free Software Foundation, Inc. @@ -282,7 +282,7 @@ WARNING: \`$1' is $msg. You should only need it if else test -z "$file" || exec >$file echo ".ab help2man is required to generate this page" - exit 1 + exit $? fi ;; diff --git a/tests/Makefile.am b/tests/Makefile.am index 52a13d5..b6e8983 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -411,6 +411,7 @@ makevars.test \ man.test \ man2.test \ man3.test \ +man4.test \ mclean.test \ mdate.test \ mdate2.test \ diff --git a/tests/man4.test b/tests/man4.test new file mode 100755 index 0000000..29b35ae --- /dev/null +++ b/tests/man4.test @@ -0,0 +1,103 @@ +#! /bin/sh +# Copyright (C) 2008 Free Software Foundation, Inc. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + +# Ensure `make dist' fails when help2man replacement man pages are created. +# +# The assumption here is the following: if the developer uses help2man to +# generate man pages from --help output, then these man pages may not be +# stored in VCS. However, they should be distributed, so that the end user +# that receives the tarball doesn't have to install help2man. If they are +# not distributed, then the developer should make help2man a prerequisite +# to building the package from a tarball, e.g., with a configure check for +# help2man that errors out if it is unavailable. In both cases it is +# sufficient to check only distributed man pages. +# +# Idea of this whole shenanigan is to allow somebody to check out sources from +# a VCS and build and install them without needing help2man installed. The +# installed man pages will be bogus in this case. Typically, this happens +# when developers ask users to try out a fix from VCS; the developers themselves +# will usually have help2man installed (or should install it). + +. ./defs || Exit 1 + +set -e + +cat > Makefile.am << 'END' +dist_man_MANS = $(srcdir)/foo.1 +dist_bin_SCRIPTS = foo +$(srcdir)/foo.1: + $(HELP2MAN) --output=$@ $(srcdir)/foo +MAINTAINERCLEANFILES = $(dist_man_MANS) +END + +cat >>configure.in <<'END' +AM_MISSING_PROG([HELP2MAN], [help2man]) +AC_OUTPUT +END + +cat > foo <<'END' +#! /bin/sh +while test $# -gt 0; do + case $1 in + -h | --help) echo "usage: $0 [OPTIONS]..."; exit 0;; + -v | --version) echo "$0 1.0"; exit 0;; + esac + shift +done +END + +cat > help2man <<'END' +#! /bin/sh +# fake help2man script that lets `missing' think it is not installed +exit 127 +END + +chmod +x foo help2man +save_PATH=$PATH +PATH=`pwd`:$PATH + +$ACLOCAL +$AUTOMAKE +$AUTOCONF +./configure +$MAKE +$MAKE dist && Exit 1 +$MAKE distcheck && Exit 1 +$MAKE distclean + +mkdir build +cd build +../configure +$MAKE +$MAKE dist 2>stderr && { cat stderr >&2; Exit 1; } +cat stderr >&2 +grep 'install help2man' stderr +$MAKE distcheck 2>stderr && { cat stderr >&2; Exit 1; } +cat stderr >&2 +grep 'install help2man' stderr + +rm -f ../help2man +PATH=$save_PATH +export PATH + +# If help2man is installed, then ensure that the recommendation works. +if (help2man --version) >/dev/null 2>&1; then + $MAKE maintainer-clean + ../configure + $MAKE + $MAKE distcheck +fi +: