From a17537af3e72d75416a466ac3579e97c1a99e1e4 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Sat, 3 Dec 2011 14:03:58 +0000 Subject: [PATCH] Give up on automake's built-in rules for generating PDF and HTML and use our own. Also include split version of the manual. --- .gitignore | 4 +- MANIFEST | 3 +- MANIFEST.SKIP | 5 +-- Makefile.am | 101 ++++++++++++++++++++++++++++++++------------------ NEWS | 1 + 5 files changed, 71 insertions(+), 43 deletions(-) diff --git a/.gitignore b/.gitignore index 81322a9..7d6996a 100644 --- a/.gitignore +++ b/.gitignore @@ -17,10 +17,10 @@ config.log config.status configure /doc/ChangeLog.OLD -/doc/manual.html /doc/manual.pdf +/doc/manual-single.html +/doc/manual-split/ /doc/manual.texi -/doc/stow.html /doc/stow.pdf /doc/stow.8 /lib/Stow.pm diff --git a/MANIFEST b/MANIFEST index d6ce9da..ae3d9b9 100644 --- a/MANIFEST +++ b/MANIFEST @@ -14,7 +14,8 @@ configure.ac COPYING default-ignore-list doc/ChangeLog.OLD -doc/stow.html +doc/manual-single.html +doc/manual.pdf doc/stow.8 doc/stow.info doc/stow.texi diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP index cfbcaad..1a0d298 100644 --- a/MANIFEST.SKIP +++ b/MANIFEST.SKIP @@ -74,12 +74,9 @@ ^autom4te\.cache/.+$ ^config\.(log|status)$ ^doc/\.dirstamp$ +^doc/manual-split/ ^doc/stamp-vti$ -^doc/manual.texi$ -^doc/manual.pdf$ -^doc/stow.pdf$ ^doc/HOWTO-RELEASE$ -^doc/manual\.html\b # Avoid test files ^tmp-testing-trees diff --git a/Makefile.am b/Makefile.am index 51502f1..9f1cbd1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -5,14 +5,9 @@ info_TEXINFOS = doc/stow.texi dist_man_MANS = doc/stow.8 dist_doc_DATA = \ README \ - doc/stow.html doc/version.texi \ + doc/manual.pdf doc/manual-single.html doc/version.texi \ ChangeLog doc/ChangeLog.OLD -# Would be nice to include the split page HTML version of the manual -# in the distribution, but automake doesn't support wildcards and I'm -# loathe to explicitly list every single page here :-( -#nobase_dist_doc_DATA = doc/manual-split/*.html - pmdir = $(libdir)/perl5 dist_pm_DATA = lib/Stow.pm pmstowdir = $(pmdir)/Stow @@ -32,6 +27,8 @@ AM_MAKEINFOFLAGS = -I $(srcdir) # to AM_INIT_AUTOMAKE which has to be silenced via -Wno-override. TEXI2DVI = texi2dvi $(AM_MAKEINFOFLAGS) +doc_deps = $(info_TEXINFOS) doc/version.texi + DEFAULT_IGNORE_LIST = $(srcdir)/default-ignore-list TESTS_DIR = $(srcdir)/t @@ -77,7 +74,7 @@ $(TESTS_OUT): CPAN_FILES = MANIFEST MANIFEST.SKIP Build.PL META.yml META.json EXTRA_DIST = \ bin/stow.in bin/chkstow.in lib/Stow.pm.in \ - doc/stow.pdf \ + doc/manual-split \ $(TESTS) t/testutil.pm \ $(TEXINFO_TEX) \ $(DEFAULT_IGNORE_LIST) \ @@ -88,7 +85,7 @@ CLEANFILES = $(bin_SCRIPTS) $(dist_pm_DATA) clean-local: -rm -rf $(TESTS_OUT) \ bin/stow bin/chkstow doc/stow.8 ChangeLog \ - doc/stow.html doc/stow.pdf + doc/manual-split doc/manual-single.html doc/manual.pdf # this is more explicit and reliable than the config file trick edit = sed -e 's|[@]PERL[@]|$(PERL)|g' \ @@ -112,27 +109,72 @@ lib/Stow.pm: lib/Stow.pm.in Makefile $(DEFAULT_IGNORE_LIST) # The below rules should only be needed by developers. ############################################################################## -doc/stow.html: doc/stow.texi - [ -d doc ] || mkdir doc # required in vpath mode - -rm -f $@ - texi2html --P=$(srcdir) --output=$@ -expandinfo -menu -monolithic -verbose $< - doc/stow.8: bin/stow Makefile [ -d doc ] || mkdir doc # required in vpath mode pod2man $< > $@ -# It's conventional to generate $project.info, but it's also nicer to -# generate manual.html and manual.pdf (which ultimately go somewhere -# like /usr/share/doc/stow/) rather than stow.html and stow.pdf, to -# make it obvious that these files contain the manual. So we have to -# jump through a few extra hoops. -install-data-hook: - cd $(DESTDIR)$(docdir) && \ - mv -f stow.html manual.html - cp $(srcdir)/doc/stow.pdf $(DESTDIR)$(docdir)/manual.pdf +# We use automake's built-in rule to generate stow.info. The built-in +# rules would also generate doc/stow.html and doc/stow.pdf, but after +# installation we want $(docdir) (typically /usr/share/doc/stow/) to +# contain manual-single.html, manual.pdf, and manual-split/*.html, to +# make it explicitly obvious that these files contain the user manual +# rather than some other Stow-related documentation. +# +# If it were not for a troublesome dependency on doc/$(am__dirstamp): +# +# http://article.gmane.org/gmane.comp.sysutils.automake.general/13192 +# +# we could have achieved this using the built-in rules combined with +# install-data-hook to rename from stow.pdf to manual.pdf etc. on +# install. Instead, by overriding the built-in rules with modified +# versions, we can kill both birds with one stone. + +doc/manual-single.html: $(doc_deps) + [ -d doc ] || mkdir doc # required in vpath mode + -rm -f $@ + texi2html --P=$(srcdir) --output=$@ -expandinfo -menu -monolithic -verbose $< + +doc/manual.pdf: $(doc_deps) + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc' \ + $(TEXI2PDF) -o $@ `test -f 'doc/stow.texi' || echo '$(srcdir)/'`doc/stow.texi + +doc/manual-split: $(doc_deps) + rm -rf $@.new + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc \ + -o $@.new `test -f 'doc/stow.texi' || echo '$(srcdir)/'`doc/stow.texi; \ + then \ + rm -rf $@; \ + mv $@.new $@; \ + else \ + rm -Rf $@.new $@; \ + exit 1; \ + fi + +# The split version of the manual is copied to $(docdir)/manual-split +# by install-data-hook. The whole subdirectory is included via +# EXTRA_DIST in order to avoid having to list each file explicitly in +# dist_doc_DATA, since automake doesn't support wildcards, and +# dist_doc_DATA cannot refer to directories while EXTRA_DIST can (go +# figure ...) + +install-data-hook: doc/manual-split + cp -r $(srcdir)/doc/manual-split $(DESTDIR)$(docdir) uninstall-hook: - rm -f $(DESTDIR)$(docdir)/manual.{html,pdf} + chmod u+w -R $(DESTDIR)$(docdir)/manual-split + rm -rf $(DESTDIR)$(docdir)/manual-split + +# Using install-data-hook has the slightly annoying disadvantage that +# by default the split version of the manual isn't automatically +# rebuilt during development by a simple `make'. A workaround hack +# for this is to piggy-back the dependency onto manual-single.html, +# which *is* automatically rebuilt by `make': +doc/manual-single.html: doc/manual-split + +# With the above hack, this probably isn't necessary but is safer to +# keep in anyway: +dist-hook: doc/manual-split ChangeLog: doc/ChangeLog.OLD Makefile @if [ -d .git ]; then \ @@ -147,16 +189,3 @@ ChangeLog: doc/ChangeLog.OLD Makefile else \ echo "Not in a git repository; can't update ChangeLog."; \ fi - -# For website only; cannot currently be included in dist_doc_DATA -# because of: -# -# http://article.gmane.org/gmane.comp.sysutils.automake.general/13192 -# -# This means that it is still included in the distribution and -# installed, but is only automatically (re)built when making a new -# distribution - if stow.texi changes during development, it has to be -# rebuilt manually via 'make pdf'. -dist-hook: pdf - -pdf: doc/stow.pdf diff --git a/NEWS b/NEWS index 7224ce4..1c98110 100644 --- a/NEWS +++ b/NEWS @@ -13,6 +13,7 @@ phase. ** Improved debugging output. ** Converted man page to POD format. +** Include PDF, and both split- and single-page HTML versions of manual in the distribution. ** Fixed code style consistency issues. ** Running configure from outside the source tree now works. ** `make distcheck' now works.