Re: missing help2man

[Ralf Wildenhues]

* 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
+: