bug#12715: [PATCH] build: do not require help2man at build-from-tarball time

[Jim Meyering]

Stefano Lattarini wrote:
> Here is the updated patch.  Sorry for the noise,
...
> Subject: [PATCH] build: graceful degradation in man pages generation if perl
>  is lacking

Thank you for the updated patch.

> Fixes coreutils bug#12715.
>
> Since commit v8.19-118-g57da212, our 'dist-hook' rule tweaks the
> distributed Makefile.in so that each man page 'man/foo.1' depends
> on the corresponding source 'man/foo.c' rather than the corresponding
> program 'man/foo'.  That is done to accommodate inferior systems that,
> lacking perl, 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 laxer 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 would be anyway unconditionally rebuilt

This is simpler than what Pádraig suggested (distribute
.1 files and insert warning if needed), but I'm inclined to
agree that simpler is better.

Does anyone know of a well-known environment/distro in which
coreutils is built without perl?  I.e., if virtually no one
builds coreutils without perl, then any attempt to coddle those
users is wasted complexity.

> * 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) should not be listed here ...
> (CLEANFILES): ... but here.
> (.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's
> not.
> (EXTRA_DIST): Distribute that shell script.
> * man/dummy-man: Be that shell script