Switch to makeinfo --html --no-split for single-page HTML manual (#21)

Remove the dependency on the ancient and unmaintained texi2html, which
was difficult to get running on most distros other than openSUSE.

There are two more modern alternative approaches which can replace
this:

  - Use texi2any
  - Use makeinfo --html --no-split

The latter seems to be the standard way these days, so we switch to
that; however we keep Makefile rules for all three, and a phony
meta-rule 'manual-single-html-all' to allow quick comparison between
them.  Make tweaks accordingly to minimise the differences and improve
the output.

The rules for the older two approaches do not get triggered by
default.

Fixes #21: https://github.com/aspiers/stow/issues/21

.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

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$

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" \

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