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/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 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 diff --git a/doc/stow.texi b/doc/stow.texi index d4e4087..6e36b97 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 @@ -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