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

  - 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

Fixes #21: https://github.com/aspiers/stow/issues/21
This commit is contained in:
Adam Spiers 2019-06-26 13:37:07 +01:00
parent 9c402559d2
commit 22ca973d59
4 changed files with 53 additions and 1 deletions

.gitignore vendored
View File

@ -20,6 +20,8 @@ configure

View File

@ -76,6 +76,8 @@

View File

@ -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 \
.PHONY: manual-single-html-all
manual-single-html-all: \
$(HTML) \
doc/manual-single-texi2html-wrapper.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 $<
-c USE_TITLEPAGE_FOR_TITLE=1 --no-split -o $@ \
`test -f 'doc/stow.texi' || echo '$(srcdir)/'`doc/stow.texi
$(PDF): $(doc_deps)

View File

@ -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