diff --git a/.gitignore b/.gitignore index 6440a89..dcb7f4d 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,8 @@ configure /doc/ChangeLog.OLD /doc/manual.pdf /doc/manual-single.html +/doc/manual-single-old-texi2html.html +/doc/manual-single-texi2html-wrapper.html /doc/manual-split/ /doc/manual.texi /doc/stow.pdf diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP index b356572..259024a 100644 --- a/MANIFEST.SKIP +++ b/MANIFEST.SKIP @@ -76,6 +76,8 @@ ^autom4te\.cache/.+$ ^config\.(log|status)$ ^doc/\.dirstamp$ +^doc/manual-single-old-texi2html\.html +^doc/manual-single-texi2html-wrapper\.html ^doc/manual-split/ ^doc/stamp-vti$ ^doc/HOWTO-RELEASE$ diff --git a/Makefile.am b/Makefile.am index ef3520a..29c6a6b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -181,10 +181,42 @@ doc/stow.8: bin/stow.in Makefile.am # install. Instead, by overriding the built-in rules with modified # versions, we can kill both birds with one stone. +# Generating the single-page HTML version used to be done with the old +# texi2html, which is no longer maintained. This rule is not used, +# but is kept to allow comparing of results during the transition, and +# potentially longer for posterity. +doc/manual-single-old-texi2html.html: $(doc_deps) + texi2html --P=$(srcdir) --output=$@ -expandinfo -menu -monolithic -verbose $< + +# One alternative to the old texi2html approach is to use the texi2html +# wrapper around texi2any which is provided as a partial drop-in replacement: +# +# https://www.gnu.org/software/texinfo/manual/texinfo/html_node/texi2html.html#texi2html +# +# Differences to the old texi2html: +# +# - Doesn't wrap @file{foo} paths with quotes, which looks better. +# - Missing certain sections +doc/manual-single-texi2html-wrapper.html: $(doc_deps) + texi2any -P $(srcdir) --output=$@ --verbose \ + -c TEXI2HTML=1 -c SHOW_MENU=1 -c MONOLITHIC=1 $< + +.PHONY: manual-single-html-all +manual-single-html-all: \ + $(HTML) \ + doc/manual-single-texi2html-wrapper.html \ + doc/manual-single-old-texi2html.html + +# Modern approach using $(MAKEINFOHTML) --no-split +# Differences to the older two approaches: +# +# - Nicer navigation links between sections $(HTML): $(doc_deps) [ -d doc ] || mkdir doc # required in vpath mode -rm -f $@ - texi2html --P=$(srcdir) --output=$@ -expandinfo -menu -monolithic -verbose $< + $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I doc -I $(srcdir)/doc \ + -c USE_TITLEPAGE_FOR_TITLE=1 --no-split -o $@ \ + `test -f 'doc/stow.texi' || echo '$(srcdir)/'`doc/stow.texi $(PDF): $(doc_deps) TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ diff --git a/NEWS b/NEWS index 3b676da..51b7e38 100644 --- a/NEWS +++ b/NEWS @@ -43,6 +43,22 @@ News file for Stow. ** Documentation fixes and enhancements +*** Remove dependency on unmaintained texi2html + + The dependency on the ancient and unmaintained texi2html for + building the single-page HTML version of the manual has been + removed, since it was difficult to get running on most distros + other than openSUSE. + + Instead use the more modern "makeinfo --html --no-split" approach. + Rules have been kept for posterity in the Makefile for the old + approach and also an "in-between" approach based on texi2any; + however these are not triggered by default. Run + + make manual-single-html-all + + to compare the three versions. + *** Fixed naming of man page The title of the generated man page was previously ending up as