[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 06/06: Revamp Texinfo manual handling, part one.
From: |
G. Branden Robinson |
Subject: |
[groff] 06/06: Revamp Texinfo manual handling, part one. |
Date: |
Thu, 11 Nov 2021 19:44:00 -0500 (EST) |
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'.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 06/06: Revamp Texinfo manual handling, part one.,
G. Branden Robinson <=