From 6764788f713fdf5fcac74fa18be8a3d50ba780e9 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Wed, 26 Jun 2019 13:25:53 +0100 Subject: [PATCH 1/4] remove trailing whitespace from lines --- AUTHORS | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/AUTHORS b/AUTHORS index 65b0ebc..0c5e88f 100644 --- a/AUTHORS +++ b/AUTHORS @@ -6,7 +6,7 @@ Contributions from Gord Matzigkeit . John Bazik wrote `fastcwd', the Perl subroutine for computing the current working directory. -Charles Briscoe-Smith wrote the fix to prevent +Charles Briscoe-Smith wrote the fix to prevent stow -D / stow -R removing initially-empty directories. Adam Lackorzynski 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 and Chris Hoobin - helped clean up the documentation for + helped clean up the documentation for version 2 and created the texi2man script. Adam Spiers refactored the backend code into new From b4cb6e775a6761445208e0eea5b48c3628508a4b Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Wed, 26 Jun 2019 13:33:48 +0100 Subject: [PATCH 2/4] Add Guillaume and myself to the list of @authors --- doc/stow.texi | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/stow.texi b/doc/stow.texi index d4e4087..e9b95fa 100644 --- a/doc/stow.texi +++ b/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 From 9c402559d2d223f505685b0bead9a75a4dae365a Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Wed, 26 Jun 2019 13:34:09 +0100 Subject: [PATCH 3/4] Include the preamble in online versions of the manual This is more inline with the suggestion in the texinfo manual: https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040top-Command.html and also the preamble is useful in all cases. --- doc/stow.texi | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/stow.texi b/doc/stow.texi index e9b95fa..6e36b97 100644 --- a/doc/stow.texi +++ b/doc/stow.texi @@ -81,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 From 22ca973d59c903d1dd7d877a8368ea7d48d9f6aa Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Wed, 26 Jun 2019 13:37:07 +0100 Subject: [PATCH 4/4] 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