[groff] 06/06: Revamp Texinfo manual handling, part one.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d79c3f3a4a19f7bf616a69558c4d3ce13690f441
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Nov 11 19:58:02 2021 +1100

    Revamp Texinfo manual handling, part one.
    
    Drop `BUILD_INFODOC` symbol.  Ship manual in GNU Info, text, and HTML
    forms in distribution archive.
    
    * Makefile.am (MAINTAINERCLEANFILES): Initialize.
      (MOSTLYCLEANADD): Drop unused variable.
    
    * configure.ac: Drop `AM_CONDITIONAL([BUILD_INFODOC]...`.
    
    * doc/doc.am (EXTRA_DIST): Rearrange shipment of our Texinfo manual
      source files to precede all of the generated forms, for clarity.  Drop
      all `BUILD_INFODOC` conditionals.  Make `build_infodoc` phony target
      depend on plain text, GNU Info, and HTML forms of Texinfo manual
      unconditionally.  Also drop unused variables `groffinfodir`,
      `groffpdfdir`, and `texi2dvi_missing`.
    
      (EXTRA_DIST, MAINTAINERCLEANFILES): Add Info form of manual.  Drop
      glob pattern attempting to match the segments that `makeinfo` breaks
      it into.  It isn't necessary for MAINTAINERCLEANFILES.
    
      (EXTRA_DIST, MAINTAINERCLEANFILES): Add text form of manual.
      (EXTRA_DIST, MAINTAINERCLEANFILES): Add HTML form of manual.
    
      (dist-hook): Depend on new (phony) target `dist-info-bits`.
    
      (dist-info-bits): Look for the info document in the build directory,
      then the source directory.  (It could be in either place depending on
      whether the build from a Git working tree is being done in or out of a
      separate build directory.) When found, copy the segments to the
      assembly area for the distribution archive.
    
      (install_infodoc): Refactor.  Remove any groff info files from the
      destination info directory using a shell glob directly instead of a
      partly redundant ls(1) command substitution.  Similarly, use a shell
      glob to cp(1) the info files (including any matched segments) to the
      destination info directory before running `install-info`.  (In this
      process I learned that `install-info` doesn't "install" anything;
      instead, it (de-)registers info files with their top-level catalog.)
    
    Tested by building:
    1. from Git working tree with separate build directory;
    2. from distribution archive w/ separate build directory (`distcheck`);
    3. from distribution archive directly;
    4. from Git working tree directly.
---
 ChangeLog    |  37 +++++++++++++++++++++
 Makefile.am  |   7 ++--
 configure.ac |   1 -
 doc/doc.am   | 107 ++++++++++++++++++++++++++++++++---------------------------
 4 files changed, 100 insertions(+), 52 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f89d50a..da558e2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,42 @@
 2021-11-11  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       Revamp Texinfo manual handling, 1/n.  Drop `BUILD_INFODOC`
+       symbol.  Ship manual in GNU Info, text, and HTML forms in
+       distribution archive.
+
+       * Makefile.am (MAINTAINERCLEANFILES): Initialize.
+       (MOSTLYCLEANADD): Drop unused variable.
+       * configure.ac: Drop `AM_CONDITIONAL([BUILD_INFODOC]...`.
+       * doc/doc.am (EXTRA_DIST): Rearrange shipment of our Texinfo
+       manual source files to precede all of the generated forms, for
+       clarity.  Drop all `BUILD_INFODOC` conditionals.  Make
+       `build_infodoc` phony target depend on plain text, GNU Info, and
+       HTML forms of Texinfo manual unconditionally.  Also drop unused
+       variables `groffinfodir`, `groffpdfdir`, and `texi2dvi_missing`.
+       (EXTRA_DIST, MAINTAINERCLEANFILES): Add Info form of manual.
+       Drop glob pattern attempting to match the segments that
+       `makeinfo` breaks it into.  It isn't necessary for
+       MAINTAINERCLEANFILES.
+       (EXTRA_DIST, MAINTAINERCLEANFILES): Add text form of manual.
+       (EXTRA_DIST, MAINTAINERCLEANFILES): Add HTML form of manual.
+       (dist-hook): Depend on new (phony) target `dist-info-bits`.
+       (dist-info-bits): Look for the info document in the build
+       directory, then the source directory.  (It could be in either
+       place depending on whether the build from a Git working tree is
+       being done in or out of a separate build directory.) When found,
+       copy the segments to the assembly area for the distribution
+       archive.
+       (install_infodoc): Refactor.  Remove any groff info files from
+       the destination info directory using a shell glob directly
+       instead of a partly redundant ls(1) command substitution.
+       Similarly, use a shell glob to cp(1) the info files (including
+       any matched segments) to the destination info directory before
+       running `install-info`.  (In this process I learned that
+       `install-info` doesn't "install" anything; instead, it
+       {de-}registers info files with their top-level catalog.)
+
+2021-11-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        * doc/doc.am (.texi.txt, .texi.html): Reorder pattern rules to
        make it clearer which formats require only `makeinfo` and which
        require `texi2dvi`.  The latter imposes more build dependencies,
diff --git a/Makefile.am b/Makefile.am
index e59b9ee..741a333 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -529,14 +529,15 @@ GROFF_V = $(GROFF_V_@AM_V@)
 GROFF_V_ = $(GROFF_V_@AM_DEFAULT_V@)
 GROFF_V_0 = @echo "  GROFF   " $@;
 
-# The following Automake variables will be overloaded by the various
-# .am files
+# The following Automake variables will be supplemented by the various
+# .am files.
 bin_PROGRAMS =
 nobase_bin_PROGRAMS =
 bin_SCRIPTS =
 dist_bin_SCRIPTS =
+# stuff that should be in distribution archives but not in source repo
+MAINTAINERCLEANFILES =
 MOSTLYCLEANFILES =
-MOSTLYCLEANADD =
 noinst_LIBRARIES =
 BUILT_SOURCES =
 CLEANFILES =
diff --git a/configure.ac b/configure.ac
index cdc425b..e65a2d1 100644
--- a/configure.ac
+++ b/configure.ac
@@ -195,7 +195,6 @@ AM_CONDITIONAL([MAKE_DONT_HAVE_RM], [test 
"x$groff_is_rm_defined" = "xno"])
 # Some programs have a "g" prefix if an existing groff installation is detected
 AM_CONDITIONAL([USEPROGRAMPREFIX], [test x$g = xg])
 
-AM_CONDITIONAL([BUILD_INFODOC], [test -n "$make_infodoc"])
 AM_CONDITIONAL([BUILD_HTML], [test -n "$make_htmldoc"])
 AM_CONDITIONAL([BUILD_HTMLEXAMPLES], [test -n "$make_htmlexamples"])
 AM_CONDITIONAL([BUILD_PDFDOC], [test -n "$make_pdfdoc"])
diff --git a/doc/doc.am b/doc/doc.am
index 53613bc..70394a7 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -311,15 +311,21 @@ if BUILD_HTML
        -rmdir $(DESTDIR)$(htmldocdir)
 endif
 
-# Texinfo doc
+# groff Texinfo manual
 #
-# Users who want to print out the groff manual are expected to have a
-# working TeX installation.  Note that texi2dvi properly honours the
-# `MAKEINFO' environment variable.
+# We can produce some formats of the manual using only 'makeinfo': GNU
+# info, plain text, and HTML.  Produce all of these by default and ship
+# them in the distribution archive ('make dist') so that people don't
+# need to have 'makeinfo' available.
 #
-# We can't use automake's facilities because the `dist` target attempts
-# to generate a PDF version of groff.texi by invoking texi2dvi without
-# the -e option, which is needed to build this file.
+# Other formats are suitable for hard copy and require a working TeX
+# installation.  We can't use Automake's facilities for PDF production
+# because the 'dist' target attempts to generate 'groff.pdf' by invoking
+# 'texi2dvi' without the '-E' option (use 'makeinfo' to expand macros),
+# which is needed to build this file.  'texi2dvi' honors the 'MAKEINFO'
+# environment variable.
+#
+# Were the foregoing not true, we would simply say this:
 #info_TEXINFOS = doc/groff.texi
 #doc_groff_TEXINFOS = doc/fdl.texi
 #
@@ -330,23 +336,36 @@ endif
 
 all: build_infodoc
 
-# Rules to generate various doc files from .texi files.
-if BUILD_INFODOC
-build_infodoc: doc/groff.info
-groffinfodir = $(infodir)
-groffpdfdir = $(infodir)
-MOSTLYCLEANFILES += doc/groff.info doc/groff.info-[0-9]
+# Provide the manual in source form.
+EXTRA_DIST += doc/groff.texi doc/fdl.texi
+
+# Define targets to generate GNU Info, plain text, and HTML from .texi.
+build_infodoc: doc/groff.info doc/groff.txt doc/groff.html
+
+EXTRA_DIST += doc/groff.info
+MAINTAINERCLEANFILES += doc/groff.info
 doc/groff.info: $(doc_srcdir)/groff.texi
        $(AM_V_at)$(MKDIR_P) $(doc_builddir)
        $(AM_V_GEN)LANG=C \
        LC_ALL=C \
        $(MAKEINFO) -o doc/groff.info --enable-encoding \
          -I$(doc_srcdir) $(doc_srcdir)/groff.texi
-else
-build_infodoc:
-endif
-EXTRA_DIST += doc/groff.texi doc/fdl.texi
 
+# Distribute the Info files.
+dist-hook: dist-info-bits
+dist-info-bits:
+       chmod u+w $(distdir)/doc
+       for d in $(doc_builddir) $(doc_srcdir); \
+       do \
+         if [ -f "$$d"/groff.info ]; \
+         then \
+           cp -f "$$d"/groff.info-* $(distdir)/doc; \
+         fi; \
+         break; \
+       done
+
+EXTRA_DIST += doc/groff.txt
+MAINTAINERCLEANFILES += doc/groff.txt
 .texi.txt:
        $(AM_V_at)$(MKDIR_P) $(doc_builddir)
        $(AM_V_GEN)LANG=C \
@@ -354,8 +373,11 @@ EXTRA_DIST += doc/groff.texi doc/fdl.texi
        $(MAKEINFO) --enable-encoding -I$(doc_srcdir) --plaintext \
          -o $@ $<
 
-# This will generate both html split into several files and html doc
-# in a single file.
+# Generate HTML, both split into several files, and as a single file.
+# 'html' and its installation counterpart 'install-html' are standard
+# Automake targets.
+EXTRA_DIST += doc/groff.html doc/groff.html.node
+MAINTAINERCLEANFILES += doc/groff.html doc/groff.html.node
 .texi.html:
        $(AM_V_at)$(MKDIR_P) $(doc_builddir)/
        $(AM_V_GEN)LANG=C \
@@ -367,13 +389,15 @@ EXTRA_DIST += doc/groff.texi doc/fdl.texi
        $(MAKEINFO) --html -I $(doc_srcdir) --no-split \
          -o $@ $<
 
-# GNU Make has a built-in variable TEXI2DVI but it is not the case of
-# all 'make' implementation.  As it default to 'texi2dvi' we simply
-# redefine it here.
-
+# GNU Make has a built-in variable TEXI2DVI, but that is not true of
+# all 'make' implementations.  As it defaults to 'texi2dvi', we (at
+# worst) harmlessly redefine it here.
 TEXI2DVI = texi2dvi
-texi2dvi_missing = no
 
+# Define pattern rules to make our Texinfo manual in DVI and PDF
+# formats.  These are not built by default.  'pdf' and 'dvi' and their
+# installation counterparts 'install-pdf' and 'install-dvi' are standard
+# Automake targets.
 .texi.dvi:
 if HAVE_TEXI2DVI
        $(AM_V_at)$(MKDIR_P) $(doc_builddir)
@@ -403,12 +427,6 @@ else
        exit 1
 endif
 
-# Targets to make all the doc in all formats. These doc are not built
-# by default. pdf, dvi, ps, html and their install equivalent
-# install-pdf, install-dvi, install-ps, install-html are standard
-# Automake targets.
-
-if BUILD_INFODOC
 doc: doc_all
 doc_all: doc_txt dvi pdf html
 doc_txt: doc/groff.txt
@@ -419,7 +437,6 @@ doc_pdf: doc/groff.pdf
 html: doc_html
 doc_html: doc/groff.html
 install-doc: install-pdf install-html
-endif
 
 distclean-local: clean_infodoc clean_otherdoc
 maintainer-clean-local: clean_infodoc clean_otherdoc
@@ -433,17 +450,20 @@ clean_otherdoc:
          $(RM) -r *.pdf *.html *.txt *.dvi *.t2p *.t2d
 
 install-data-local: install_infodoc
-if BUILD_INFODOC
 install_infodoc: doc/groff.info
        -test -d $(DESTDIR)$(infodir) \
          || $(mkinstalldirs) $(DESTDIR)$(infodir)
-         for p in doc/groff.info `ls doc/groff.info*`; do \
-           f=`basename $$p`; \
-           $(RM) $(DESTDIR)$(infodir)/$$f; \
-           $(INSTALL_DATA) $$p $(DESTDIR)$(infodir)/$$f; \
-         done
-       $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) \
-         $(DESTDIR)$(infodir)/groff.info
+       $(RM) $(DESTDIR)/doc/groff.info*
+       for d in $(doc_builddir) $(doc_srcdir); \
+       do \
+         if [ -f "$$d"/groff.info ]; \
+         then \
+           cp "$$d"/groff.info* $(DESTDIR)$(infodir); \
+           $(INSTALL_INFO) --info-file="$$d"/groff.info \
+             --info-dir=$(DESTDIR)$(infodir); \
+         fi; \
+         break; \
+       done
 install-pdf-local: doc/groff.pdf
        -test -d $(DESTDIR)$(pdfdocdir) \
          || $(mkinstalldirs) $(DESTDIR)$(pdfdocdir)
@@ -455,29 +475,20 @@ install-html-local: doc/groff.html
          $(DESTDIR)$(htmldocdir)/groff.html.mono
        cp -r $(top_builddir)/doc/groff.html.node \
          $(DESTDIR)$(htmldocdir)
-else
-install_infodoc:
-endif
 
 uninstall-local: uninstall_infodoc uninstall-pdf uninstall-html
 uninstall_doc: uninstall-local
 uninstall-doc: uninstall-local
 uninstall_infodoc:
-if BUILD_INFODOC
        -$(INSTALL_INFO) --remove --info-dir=$(DESTDIR)$(infodir) \
          $(DESTDIR)$(infodir)/groff.info
        -for f in `ls $(DESTDIR)$(infodir)/groff.info*`; do \
          $(RM) $$f; \
        done
-endif
 uninstall-pdf:
-if BUILD_INFODOC
        -$(RM) -f $(DESTDIR)$(pdfdocdir)/groff.pdf 
-endif
 uninstall-html:
-if BUILD_INFODOC
        -$(RM) -r $(DESTDIR)$(htmldocdir)/groff.html.*
-endif
 
 # File used by contrib/hdtbl and contrib/pdfmark. It is distributed in
 # doc.eps. We try in priority to use the file in 'doc'.