diff options
-rw-r--r-- | Makefile.am | 20 | ||||
-rw-r--r-- | NEWS | 13 | ||||
-rwxr-xr-x | man/dummy-man | 72 | ||||
-rw-r--r-- | man/local.mk | 25 |
4 files changed, 99 insertions, 31 deletions
diff --git a/Makefile.am b/Makefile.am index 0232090b8..5eaa45b17 100644 --- a/Makefile.am +++ b/Makefile.am @@ -93,29 +93,11 @@ BUILT_SOURCES = .version .version: $(AM_V_GEN)echo $(VERSION) > $@-t && mv $@-t $@ -# In general, we run help2man to build a man page from the binary's --help -# output, but when building from a just-unpacked distribution tarball, we -# must not do that, since help2man uses perl. We don't want to depend on -# perl in that case. In general, the .1 file does indeed depend on the -# binary. I.e., for cat, we have this Makefile dependency: -# man/cat.1: src/cat -# That means that once we build src/cat, we would trigger the .x.1 -# rule which runs help2man. The trick is simply to change the RHS to -# "src/cat.c" in the $(distdir) that we're about to tar and compress. -# Also handle the three exceptions corresponding to the three binaries -# for which there is no like-named .c file: dir, vdir, ginstall. -.PHONY: do-not-require-help2man -do-not-require-help2man: - perl -pi -e 's,^(man/.+?\.1:\s*src/.+?)$$,$$1.c,;' \ - -e 's,^(man/.+?\.1:\s*src)/ginstall\.c$$,$$1/install.c,;' \ - -e 's,^(man/.+?\.1:\s*src)/v?dir\.c$$,$$1/ls.c,;' \ - $(distdir)/Makefile.in - # Arrange so that .tarball-version appears only in the distribution # tarball, and never in a checked-out repository. # The perl substitution is to change some key uses of "rm" to "/bin/rm". # See the rm_subst comment for details. -dist-hook: gen-ChangeLog do-not-require-help2man +dist-hook: gen-ChangeLog $(AM_V_GEN)echo $(VERSION) > $(distdir)/.tarball-version $(AM_V_at)perl -pi -e '$(rm_subst)' $(distdir)/Makefile.in @@ -8,6 +8,19 @@ GNU coreutils NEWS -*- outline -*- consistently padded with spaces, rather than with zeros for certain widths. [bug introduced in TEXTUTILS-1_22i] +** Build-related + + Perl is now more of a prerequisite. It has long been required in order + to run (not skip) a significant percentage of the tests. Now, it is + also required in order to generate proper man pages, via help2man. The + generated man/*.1 man pages are no longer distributed. Building without + perl, you would create stub man pages. Thus, while perl is not an + official prerequisite (build and "make check" will still succeed), any + resulting man pages would be inferior. In addition, this fixes a bug + in distributed (not from clone) Makefile.in that could cause parallel + build failure when building from modified sources, as is common practice + for a patched distribution package. + * Noteworthy changes in release 8.20 (2012-10-23) [stable] 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 diff --git a/man/local.mk b/man/local.mk index ebc111da1..2c05bb6cc 100644 --- a/man/local.mk +++ b/man/local.mk @@ -16,17 +16,24 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see <http://www.gnu.org/licenses/>. -EXTRA_DIST += man/help2man +EXTRA_DIST += man/help2man man/dummy-man + +## Graceful degradation for systems lacking perl. +if HAVE_PERL +run_help2man = $(PERL) -- $(srcdir)/man/help2man +else +run_help2man = $(SHELL) $(srcdir)/man/dummy-man +endif man1_MANS = @man1_MANS@ -EXTRA_DIST += $(man1_MANS) $(man1_MANS:.1=.x) +EXTRA_DIST += $(man1_MANS:.1=.x) EXTRA_MANS = @EXTRA_MANS@ -EXTRA_DIST += $(EXTRA_MANS) $(EXTRA_MANS:.1=.x) +EXTRA_DIST += $(EXTRA_MANS:.1=.x) ALL_MANS = $(man1_MANS) $(EXTRA_MANS) -MAINTAINERCLEANFILES += $(ALL_MANS) +CLEANFILES += $(ALL_MANS) # This is required because we have subtle inter-directory dependencies: # in order to generate all man pages, even those for which we don't @@ -161,13 +168,7 @@ man/whoami.1: src/whoami man/yes.1: src/yes .x.1: - $(AM_V_GEN)case '$(PERL)' in \ - *"/missing "*) \ - echo 'WARNING: cannot update man page $@ since perl is missing' \ - 'or inadequate' 1>&2 \ - exit 0;; \ - esac; \ - name=`echo $@ | sed -e 's|.*/||' -e 's|\.1$$||'` || exit 1; \ + $(AM_V_GEN)name=`echo $@ | sed 's|.*/||; s|\.1$$||'` || exit 1; \ ## Ensure that help2man runs the 'src/ginstall' binary as 'install' when ## creating 'install.1'. Similarly, ensure that it uses the 'src/[' binary ## to create 'test.1'. @@ -184,7 +185,7 @@ man/yes.1: src/yes && rm -rf $$t \ && $(MKDIR_P) $$t \ && (cd $$t && $(LN_S) '$(abs_top_builddir)/src/'$$prog $$name) \ - && $(PERL) -- $(srcdir)/man/help2man \ + && $(run_help2man) \ --source='$(PACKAGE_STRING)' \ --include=$(srcdir)/man/$$name.x \ --output=$$t/$$name.1 $$t/$$name \ |