summaryrefslogtreecommitdiff
path: root/man/dummy-man
diff options
context:
space:
mode:
authorStefano Lattarini <stefano.lattarini@gmail.com>2012-09-11 20:54:30 +0200
committerJim Meyering <jim@meyering.net>2012-10-26 12:04:12 +0200
commit48536bfe8f7fe1d41d8ca71dc51c0550adb3b89a (patch)
tree63a80ab6a364c03f2ae1d5edfa2b7047f56753e7 /man/dummy-man
parent74da4c80470bffe3ccfaead598dad36bf64f1b97 (diff)
downloadcoreutils-48536bfe8f7fe1d41d8ca71dc51c0550adb3b89a.tar.xz
build: man page generation: degrade gracefully when perl is lacking
Since commit v8.19-118-g57da212, our 'dist-hook' rule tweaked the distributed Makefile.in to make each man page 'man/foo.1' depend on the corresponding source 'src/foo.c' rather than the corresponding program 'src/foo'. That was done to accommodate systems without perl, which cannot run help2man to regenerate the manpage after its corresponding program has been built. This seems a right and proper graceful degradation, in that the man pages dependencies are still 100% correct in a git checkout, while being more lax but "more portable" in a distribution tarball. Alas, that is not the case in practice, as it turns out the tweaked Makefile makes the building of man pages unreliable and potentially incorrect! In fact, assume that instead of the correct a dependency: man/ls.1: src/ls we have the laxer one: man/ls.1: src/ls.c and think of what happens if a user modifies, say, 'src/ls.c', and then runs "make -j4" to rebuild everything. The make process will see that it has to rebuild the man page 'man/ls.1' (because its prerequisite 'src/ls.c' has changed), but won't see that it has to rebuild 'src/ls' *before* re-running 'help2man' to generate that man page; so, if 'man/ls.1' is rebuilt before 'src/ls' (which can happen with concurrent make), our user will get either a build error (if 'src/ls' did non exist) or, worse, a man page with an up-to-date timestamp but an out-of-date content. And what's even worse in all of this is that this problem will be present also for users who have perl installed: this is not a "graceful degradation" at all! In our situation, the best and simplest way to implement a graceful degradation it to keep the correct dependencies for man pages (that is, "man/ls.1: src/ls"), and if perl is not present, just generate dummy man pages reporting that built-time issue and redirecting the user back to either the info documentation or the '--help' output. As a consequence of this change, we also stop distributing man pages, since they will now be generated unconditionally. * Makefile.am (do-not-require-help2man): Remove. (dist-hook): Don't depend on it. * man/local.mk: Remove an obsolete comment. (EXTRA_DIST): Stop distributing generated man pages. ($(EXTRA_MANS)): This no longer needs to depend on $(all_programs). (MAINTAINERCLEANFILES): $(ALL_MANS) Do not list it here, and ... (CLEANFILES): ... list it here, instead. (.x.1): Instead of warning if perl is missing, but then trying to run 'help2man' unconditionally, simply run ... (run_help2man): ... the command referenced by this new variable, that expands to a proper invocation of 'help2man' if perl is present, and to an invocation of a shell script generating a dummy manpage if it is not. (EXTRA_DIST): Distribute that shell script. * man/dummy-man: New shell script. * NEWS (Build-related): Mention this. Fixes coreutils http://bugs.gnu.org/12715.
Diffstat (limited to 'man/dummy-man')
-rwxr-xr-xman/dummy-man72
1 files changed, 72 insertions, 0 deletions
diff --git a/man/dummy-man b/man/dummy-man
new file mode 100755
index 000000000..306937628
--- /dev/null
+++ b/man/dummy-man
@@ -0,0 +1,72 @@
+#!/bin/sh
+# Poor man's placeholder for help2man invocation on systems lacking perl;
+# it generates a dummy man page stating that a proper one could not be
+# generated, and redirecting the user back to either the info
+# documentation or the '--help' output.
+
+set -e; set -u
+
+fatal_ ()
+{
+ printf '%s: %s\n' "$0" "$*" >&2
+ exit 1
+}
+
+basename_ ()
+{
+ printf '%s\n' "$1" | sed 's,.*/,,'
+}
+
+output=
+source="GNU coreutils"
+while test $# -gt 0; do
+ case $1 in
+ # Help2man options we recognize and handle.
+ --output=*) output=`expr x"$1" : x'--output=\(.*\)'`;;
+ --output) shift; output=$1;;
+ --source=*) source=`expr x"$1" : x'--source=\(.*\)'`;;
+ --source) shift; source=$1;;
+ # Recognize (as no-op) other help2man options that might be used
+ # in the makefile.
+ --include=*);;
+ --include) shift;;
+ -*) fatal_ "invalid or unrecognized help2man option '$1'";;
+ --) shift; break;;
+ *) break;;
+ esac
+ shift
+done
+
+test $# -gt 0 || fatal_ "missing argument"
+test $# -le 1 || fatal_ "too many non-option arguments"
+
+baseout=`basename_ "$output"`
+sed 's/^/WARNING: /' >&2 <<END
+Cannot create proper '$baseout' man page, since perl is missing or
+inadequate on this system. Creating a stub man page instead.
+END
+
+progname=`basename_ "$1"`
+year=`LC_ALL=C date +%Y`
+bs='\'
+
+cat >"$output" <<END
+.TH "$progname" 1 "$year" "$source" "User Commands"
+.SH NAME
+$progname $bs- a $source program
+.SH DESCRIPTION
+.B OOOPS!
+Due to the lack of perl on the build system, we were
+unable to create a proper manual page for
+.B $progname.
+For concise option descriptions, run
+.IP
+.B env $progname --help
+.PP
+The full documentation for
+.B $progname
+is maintained as a Texinfo manual, which should be accessible
+on your system via the command
+.IP
+.B info coreutils $bs(aq$progname invocation$bs(aq
+END