From 22ca973d59c903d1dd7d877a8368ea7d48d9f6aa Mon Sep 17 00:00:00 2001
From: Adam Spiers <stow@adamspiers.org>
Date: Wed, 26 Jun 2019 13:37:07 +0100
Subject: [PATCH] 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    |  2 ++
 MANIFEST.SKIP |  2 ++
 Makefile.am   | 34 +++++++++++++++++++++++++++++++++-
 NEWS          | 16 ++++++++++++++++
 4 files changed, 53 insertions(+), 1 deletion(-)

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