switch from unmaintained texi2html to makeinfo --html --no-split (#42)

switch from unmaintained texi2html to makeinfo --html --no-split

.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

AUTHORS

@@ -6,7 +6,7 @@ Contributions from Gord Matzigkeit <gord@enci.ucalgary.ca>.
 John Bazik wrote `fastcwd', the Perl subroutine for computing the
 current working directory.
 
-Charles Briscoe-Smith <cpbs@debian.org> wrote the fix to prevent 
+Charles Briscoe-Smith <cpbs@debian.org> wrote the fix to prevent
 stow -D / stow -R removing initially-empty directories.
 
 Adam Lackorzynski <al10@inf.tu-dresden.de> wrote the fix to prevente
@@ -19,17 +19,17 @@ in order to implement:
 
     1. defered operations,
     2. option parsing via Getopt::Long,
-    3. options to support shared files, 
+    3. options to support shared files,
     4. support for multiple operations per invocation,
-    5. default command line arguments via '.stowrc' and '~/.stowrc' files, 
+    5. default command line arguments via '.stowrc' and '~/.stowrc' files,
     6. better cooperation between multiple stow directories,
-    7. a test suite (and support code) to ensure that everything still works.  
+    7. a test suite (and support code) to ensure that everything still works.
 
 As these changes required a dramatic reorganisation of the code, very little
 was left untouched, and so Stow's major version was bumped up to version 2.
 
 Austin Wood <austin.wood@rmit.edu.au> and Chris Hoobin
-<christopher.hoobin@rmit.edu.au> helped clean up the documentation for 
+<christopher.hoobin@rmit.edu.au> helped clean up the documentation for
 version 2 and created the texi2man script.
 
 Adam Spiers <stow@adamspiers.org> refactored the backend code into new

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

doc/stow.texi

@@ -63,7 +63,9 @@ approved by the Free Software Foundation.
 @title Stow @value{VERSION}
 @subtitle Managing the installation of software packages
 @author Bob Glickstein, Zanshin Software, Inc.
-@author Kahlil Hodgson, RMIT Univerity, Australia.
+@author Kahlil Hodgson, RMIT University, Australia.
+@author Guillaume Morin
+@author Adam Spiers
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -79,12 +81,10 @@ approved by the Free Software Foundation.
 @node Top
 @top
 
-@ifinfo
 This manual describes GNU Stow @value{VERSION} (@value{UPDATED}), a
 symlink farm manager which takes distinct sets of software and/or data
 located in separate directories on the filesystem, and makes them
 appear to be installed in a single directory tree.
-@end ifinfo
 @end ifnottex
 
 @menu