[groff] 02/25: [doc]: Refactor handling of "gnu.eps" file.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e78bd20d54de27c2c20deddd1bba1f00e770f85b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Mar 27 00:34:06 2022 +1100

    [doc]: Refactor handling of "gnu.eps" file.
    
      * doc/doc.am: Put "gnu.eps" in a Make macro, `DOC_GNU_EPS`.
    
      ($(PROCESSEDEXAMPLEFILES) $(PROCESSEDDOCFILES), doc/webpage.html,
      install_doc_examples): Migrate dependency to `DOC_GNU_EPS`.
    
      (doc/webpage.ps): Add (missing) dependency on `DOC_GNU_EPS`.
    
      (DOC_GROFF_ONLY): Drop `-I` flag; it's not necessary given the
      following.
    
      (.ms.ps): Drop `-mwww` argument from suffix rule.  A truly generic ms
      document won't need it.
    
      (doc/webpage.ps): Add target rule.  Include `-mwww` argument.
    
      (doc/webpage.ps, doc/webpage.html): Pass `-I` option to `DOC_GROFF`
      and `DOC_GROFF_ONLY` (respectively) to enable location of "gnu.eps"
      file.  Search the build and source trees' "doc" directories because
      the file can be generated as part of the build or can come with the
      distribution archive.
    
      (clean_maintdoc): Add phony target to dispose of `DOC_GNU_EPS`.
    
      (maintainer-clean-local): Depend on "clean_maintdoc".
    
    * contrib/hdtbl/hdtbl.am (nodist_hdtblexample_DATA,
      HDTBLPROCESSEDEXAMPLEFILES):
    * contrib/pdfmark/pdfmark.am (PDFDOCFILES): Replace hard-coded "gnu.eps"
      file name with expansion of `DOC_GNU_EPS`.
    
    * contrib/hdtbl/hdtbl.am (HDTBLPROCESSEDEXAMPLEFILES): Pass `-I` option
      to `HDTBLGROFF` to enable location of "gnu.eps" file (for
      "mixedpickles.roff" document).
    
    * contrib/mom/mom.am (MOMPROCESSEDEXAMPLEFILES): Drop dependency on
      gnu.eps.  No mom document appears to require this file; it came in
      with the initial Automake file for mom in commit 4d84d0f1d, 27 January
      2015, and may have been a copy-and-paste error.
    
    * contrib/pdfmark/pdfmark.am (contrib/pdfmark/pdfmark.pdf): Pass `-I`
      option to pdfroff(1) to enable location of "gnu.eps" file.
    
    * tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh:
    * tmac/tests/pdfpic_falls-back-to-PSPIC.sh: Update tests to look for
      "gnu.eps" in "doc" directory of build tree.
---
 ChangeLog                                          | 28 ++++++++++++
 contrib/hdtbl/ChangeLog                            |  9 ++++
 contrib/hdtbl/hdtbl.am                             |  6 +--
 contrib/mom/ChangeLog                              |  7 +++
 contrib/mom/mom.am                                 |  2 +-
 contrib/pdfmark/ChangeLog                          |  7 +++
 contrib/pdfmark/pdfmark.am                         | 10 +++--
 doc/doc.am                                         | 50 +++++++++++++++-------
 .../pdfpic_does-not-choke-on-bad-pdfinfo-output.sh | 21 ++++++++-
 tmac/tests/pdfpic_falls-back-to-PSPIC.sh           | 24 +++++++++--
 10 files changed, 134 insertions(+), 30 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7f15a1d7..6cbff1fe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,31 @@
+2022-03-28  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [doc]: Refactor handling of "gnu.eps" file.
+
+       * doc/doc.am: Put "gnu.eps" in a Make macro, `DOC_GNU_EPS`.
+       ($(PROCESSEDEXAMPLEFILES) $(PROCESSEDDOCFILES),
+       doc/webpage.html, install_doc_examples): Migrate dependency to
+       `DOC_GNU_EPS`.
+       (doc/webpage.ps): Add (missing) dependency on `DOC_GNU_EPS`.
+       (DOC_GROFF_ONLY): Drop `-I` flag; it's not necessary given the
+       following.
+       (.ms.ps): Drop `-mwww` argument from suffix rule.  A truly
+       generic ms document won't need it.
+       (doc/webpage.ps): Add target rule.  Include `-mwww` argument.
+       (doc/webpage.ps, doc/webpage.html): Pass `-I` option to
+       `DOC_GROFF` and `DOC_GROFF_ONLY` (respectively) to enable
+       location of "gnu.eps" file.  Search the build and source trees'
+       "doc" directories because the file can be generated as part of
+       the build or can come with the distribution archive.
+       (EXTRA_DIST): Drop redundant inclusion of "doc/gnu.xpm".
+       (clean_maintdoc): Add phony target to dispose of `DOC_GNU_EPS`.
+       (maintainer-clean-local): Depend on "clean_maintdoc".
+
+       * tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh:
+       * tmac/tests/pdfpic_falls-back-to-PSPIC.sh: Update tests to look
+       for "gnu.eps" in "doc" directory of build tree.  Give generated
+       files distinguishable names so their tests can run concurrently.
+
 2022-03-23  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/doc.am: Add new macro `PROCESSEDDOCFILES_PS` to isolate
diff --git a/contrib/hdtbl/ChangeLog b/contrib/hdtbl/ChangeLog
index b6c16051..7f95a28f 100644
--- a/contrib/hdtbl/ChangeLog
+++ b/contrib/hdtbl/ChangeLog
@@ -1,3 +1,12 @@
+2022-03-26  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * hdtbl.am (nodist_hdtblexample_DATA,
+       HDTBLPROCESSEDEXAMPLEFILES): Replace hard-coded "gnu.eps" file
+       name with expansion of `DOC_GNU_EPS`.
+       (HDTBLPROCESSEDEXAMPLEFILES): Pass `-I` option to `HDTBLGROFF`
+       to enable location of "gnu.eps" file (for "mixedpickles.roff"
+       document).
+
 2021-10-21  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * hdtbl.am:
diff --git a/contrib/hdtbl/hdtbl.am b/contrib/hdtbl/hdtbl.am
index 1e219a82..8652d49d 100644
--- a/contrib/hdtbl/hdtbl.am
+++ b/contrib/hdtbl/hdtbl.am
@@ -83,7 +83,7 @@ dist_hdtblexample_DATA = $(HDTBLEXAMPLEFILES)
 nodist_hdtblexample_DATA = \
   $(HDTBLGENFILES) \
   $(HDTBLPROCESSEDEXAMPLEFILES) \
-  gnu.eps
+  $(DOC_GNU_EPS)
 else
 EXTRA_DIST += $(HDTBLEXAMPLEFILES)
 endif
@@ -116,7 +116,7 @@ SUFFIXES += .roff .in .ps
 
 .roff.ps:
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
-       && $(HDTBLGROFF) -Tps \
+       && $(HDTBLGROFF) -I $(doc_builddir) -I $(doc_srcdir) -Tps \
             -dfontpath=$(top_srcdir)/font \
             -dsopath=$(hdtbl_srcdir)/ \
             -mhdtbl $< >$@
@@ -127,7 +127,7 @@ SUFFIXES += .roff .in .ps
               -e "s|[@]EGREP[@]|$(EGREP)|" $< >$@
 
 
-$(HDTBLPROCESSEDEXAMPLEFILES): gnu.eps groff troff eqn pic tbl \
+$(HDTBLPROCESSEDEXAMPLEFILES): $(DOC_GNU_EPS) groff troff eqn pic tbl \
   contrib/hdtbl/examples/common.roff
 
 uninstall_groffdirs: uninstall-hdtbl-hook
diff --git a/contrib/mom/ChangeLog b/contrib/mom/ChangeLog
index 94dabda8..d94aab0d 100644
--- a/contrib/mom/ChangeLog
+++ b/contrib/mom/ChangeLog
@@ -1,3 +1,10 @@
+2022-03-26  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * mom.am (MOMPROCESSEDEXAMPLEFILES): Drop dependency on gnu.eps.
+       No mom document appears to require this file; it came in with
+       the initial Automake file for mom in commit 4d84d0f1d, 27
+       January 2015, and may have been a copy-and-paste error.
+
 2021-10-21  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * mom.am:
diff --git a/contrib/mom/mom.am b/contrib/mom/mom.am
index 7342b06b..36dcb6db 100644
--- a/contrib/mom/mom.am
+++ b/contrib/mom/mom.am
@@ -152,7 +152,7 @@ SUFFIXES += .mom .pdf
 
 $(MOMPROCESSEDEXAMPLEFILES): $(MOMNORMALFILES) \
   groff troff gropdf pdfmom penguin.ps penguin.pdf \
-  gnu.eps font/devpdf/build_font_files
+  font/devpdf/build_font_files
 
 penguin.ps:
        $(AM_V_at)cp $(mom_srcdir)/examples/penguin.ps $@
diff --git a/contrib/pdfmark/ChangeLog b/contrib/pdfmark/ChangeLog
index 3a4bdd00..b9d7e0bf 100644
--- a/contrib/pdfmark/ChangeLog
+++ b/contrib/pdfmark/ChangeLog
@@ -1,3 +1,10 @@
+2022-03-26  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * pdfmark.am (PDFDOCFILES): Replace hard-coded "gnu.eps"
+       file name with expansion of `DOC_GNU_EPS`.
+       (contrib/pdfmark/pdfmark.pdf): Pass `-I` option to pdfroff(1) to
+       enable location of "gnu.eps" file.
+
 2021-10-24  Keith Marshall  <keith.d.marshall@ntlworld.com>
 
        Adapt to accommodate global XH and XN implementations.
diff --git a/contrib/pdfmark/pdfmark.am b/contrib/pdfmark/pdfmark.am
index 9a2d0308..5fe6938d 100644
--- a/contrib/pdfmark/pdfmark.am
+++ b/contrib/pdfmark/pdfmark.am
@@ -65,12 +65,14 @@ PDFROFF=\
 
 contrib/pdfmark/pdfmark.pdf: contrib/pdfmark/pdfmark.ms
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
-       && $(PDFROFF) -mspdf --stylesheet=$(pdfmark_srcdir)/cover.ms \
-            $(top_srcdir)/contrib/pdfmark/pdfmark.ms >$@
+       && $(PDFROFF) -I $(doc_builddir) -I $(doc_srcdir) -mspdf \
+         --stylesheet=$(pdfmark_srcdir)/cover.ms \
+         $(top_srcdir)/contrib/pdfmark/pdfmark.ms >$@
 
 # The pdf files use the local script to generate.
-$(PDFDOCFILES): pdfroff groff troff gropdf 
-$(PDFDOCFILES): $(dist_devpsfont_DATA) $(nodist_devpsfont_DATA) gnu.eps
+$(PDFDOCFILES): pdfroff groff troff gropdf
+$(PDFDOCFILES): $(dist_devpsfont_DATA) $(nodist_devpsfont_DATA) \
+  $(DOC_GNU_EPS)
 
 pdfroff: contrib/pdfmark/pdfroff.sh $(SH_DEPS_SED_SCRIPT)
        $(AM_V_GEN)sed -f $(SH_DEPS_SED_SCRIPT) \
diff --git a/doc/doc.am b/doc/doc.am
index 01f2dfa2..544fe147 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -28,8 +28,10 @@ DOC_SED = $(SED) \
 DOC_GROFF_ONLY=\
   GROFF_COMMAND_PREFIX= \
   GROFF_BIN_PATH="$(GROFF_BIN_PATH)" \
-  $(GROFFBIN) -I$(abs_top_builddir) -M $(doc_srcdir) \
-       $(TFLAG) $(FFLAG) -pet -ww -b
+  $(GROFFBIN) -M $(doc_srcdir) $(TFLAG) $(FFLAG) -pet -ww -b
+
+# This image file is used by several documents in the groff source tree.
+DOC_GNU_EPS=doc/gnu.eps
 
 # A dance is required to embed a literal newline inside a sed expression
 # inside a shell command executed as part of a Make target rule.
@@ -58,6 +60,7 @@ DOCFILES= \
   doc/pic.ms
 # Files that undergo a transformation prior to groff processing
 GENERATEDDOCFILES = \
+  $(DOC_GNU_EPS) \
   doc/meintro.me \
   doc/meintro_fr.me \
   doc/meref.me
@@ -142,7 +145,6 @@ exampleimagedir = $(exampledir)/img
 MOSTLYCLEANFILES += doc/examples.stamp
 
 EXTRA_DIST += \
-  doc/gnu.xpm \
   doc/txi-en.tex
 
 # Introduce variables to house the groff man pages.  We break the list
@@ -270,12 +272,11 @@ _fr.me._fr.ps:
 
 .ms.ps:
        $(GROFF_V)$(MKDIR_P) `dirname $@` \
-       && $(DOC_GROFF) -Tps -ms -mwww >$@
+       && $(DOC_GROFF) -Tps -ms >$@
 
 $(PROCESSEDEXAMPLEFILES) $(PROCESSEDDOCFILES): \
   $(bin_PROGRAMS) \
   $(prefixexecbin_PROGRAMS) \
-  gnu.eps \
   $(hdtbltmac_DATA) \
   $(dist_tmac_DATA) $(nodist_tmac_DATA)
 
@@ -298,20 +299,27 @@ doc/examples.stamp: doc/groff.css
          cp $(doc_srcdir)/groff.css $(doc_builddir)
        $(AM_V_at)echo timestamp > $@
 
+doc/webpage.ps: $(DOC_GNU_EPS)
+doc/webpage.ps: doc/webpage.ms
+       $(GROFF_V)$(MKDIR_P) `dirname $@` \
+       && $(DOC_GROFF) -I $(doc_builddir) -I $(doc_srcdir) -Tps -ms \
+         -mwww >$@
+
 doc/webpage.html: $(bin_PROGRAMS) $(prefixexecbin_PROGRAMS)
 doc/webpage.html: doc/examples.stamp $(devhtmlfont_DATA)
 doc/webpage.html: $(dist_devpsfont_DATA) $(nodist_devpsfont_DATA)
 doc/webpage.html: \
   $(doc_srcdir)/webpage.ms \
-  gnu.eps \
+  $(DOC_GNU_EPS) \
   $(doc_srcdir)/groff.css
        $(GROFF_V)$(MKDIR_P) doc \
        && cd $(doc_builddir) \
        && nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \
          $(DOC_SED) -e "1i\\$$nl.lf 1 $(doc_srcdir)/webpage.ms$$nl" \
          $(doc_srcdir)/webpage.ms \
-          | $(DOC_GROFF_ONLY) -P-jwebpage -P-nrb -P-Iwebpage \
-                              -P-D$(imagedir) -Thtml -ms > webpage.html
+          | $(DOC_GROFF_ONLY) -I $(doc_builddir) -I $(doc_srcdir) \
+            -P-jwebpage -P-nrb -P-Iwebpage -P-D$(imagedir) -Thtml -ms \
+            > webpage.html
 
 doc/grnexmpl.ps: $(doc_srcdir)/grnexmpl.me $(doc_srcdir)/grnexmpl.g \
   grn eqn
@@ -371,7 +379,7 @@ if BUILD_HTML
 endif
 
 install-data-hook: install_doc_examples
-install_doc_examples: gnu.eps
+install_doc_examples: $(DOC_GNU_EPS)
 if BUILD_EXAMPLES
 # Prefer gnu.eps in builddir over srcdir.
        d=.; test -f "gnu.eps" || d=$(doc_srcdir); \
@@ -559,7 +567,7 @@ doc_html: doc/groff.html
 install-doc: install-pdf install-html
 
 distclean-local: clean_infodoc clean_otherdoc
-maintainer-clean-local: clean_infodoc clean_otherdoc
+maintainer-clean-local: clean_infodoc clean_otherdoc clean_maintdoc
 clean_infodoc:
        -$(RM) $(doc_builddir)/groff.info*
        -$(RM) $(doc_builddir)/groff.pdf
@@ -568,6 +576,8 @@ clean_infodoc:
 clean_otherdoc:
        -cd $(doc_builddir) && \
          $(RM) -r *.pdf *.html *.txt *.dvi *.t2p *.t2d
+clean_maintdoc:
+       -$(RM) $(DOC_GNU_EPS)
 
 install-data-local: install_infodoc
 install_infodoc: doc/groff.info
@@ -610,11 +620,10 @@ uninstall-pdf:
 uninstall-html:
        -$(RM) -r $(DESTDIR)$(htmldocdir)/groff.html.*
 
-# File used by contrib/hdtbl and contrib/pdfmark. It is distributed in
-# doc.eps. We try in priority to use the file in 'doc'.
+# An image of a gnu in enscapsulated PostScript is generated during the
+# build process if possible.
 EXTRA_DIST += doc/gnu.xpm
-MOSTLYCLEANFILES += gnu.eps
-gnu.eps:
+$(DOC_GNU_EPS): doc/gnu.xpm
        $(AM_V_GEN)if test -f $(top_srcdir)/doc/gnu.eps; then \
          cp $(top_srcdir)/doc/gnu.eps . ; \
        elif test -f $(top_builddir)/doc/gnu.eps; then \
@@ -636,12 +645,21 @@ gnu.eps:
          xpmtoppm $(top_srcdir)/doc/gnu.xpm | pnmdepth 15 \
            | $(pnmtops_nosetpage) -noturn -rle >$@ ; \
        fi
+       $(AM_V_GEN)test -f $(top_builddir)/doc/gnu.eps
 
-# Copy gnu.eps in 'doc' directory
+# Provide a copy of the image in the distribution archive to accommodate
+# systems without a tool to generate it from an X pixmap.
 dist-hook: dist-gnueps
 dist-gnueps:
        chmod u+w $(distdir)/doc
-       cp -f gnu.eps $(distdir)/doc
+       for d in $(doc_builddir) $(doc_srcdir); \
+       do \
+         if [ -f "$$d"/$(DOC_GNU_EPS) ]; \
+         then \
+           cp -f "$$d"/$(DOC_GNU_EPS) $(distdir)/doc; \
+         fi; \
+         break; \
+       done
 
 
 # Local Variables:
diff --git a/tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh 
b/tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh
index 8dd4a5eb..15e76a8e 100755
--- a/tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh
+++ b/tmac/tests/pdfpic_does-not-choke-on-bad-pdfinfo-output.sh
@@ -19,8 +19,8 @@
 #
 
 groff="${abs_top_builddir:-.}/test-groff"
-gnu_eps="${abs_top_builddir:-.}/gnu.eps"
-gnu_pdf="${abs_top_builddir:-.}/gnu.pdf"
+# Give the output a name that won't collide with another test.
+gnu_pdf="${abs_top_builddir:-.}/doc/gnu-no-choke-on-pdfinfo.pdf"
 
 # Regression-test Savannah #58206.
 
@@ -30,6 +30,23 @@ then
     exit 77 # skip
 fi
 
+# Locate directory containing our test artifacts.
+artifact_dir=
+
+for buildroot in . .. ../..
+do
+    d=$buildroot/doc
+    if [ -f $d/gnu.eps ]
+    then
+        artifact_dir=$d
+        gnu_eps=$artifact_dir/gnu.eps
+        break
+    fi
+done
+
+# If we can't find it, we can't test.
+test -z "$artifact_dir" && exit 77 # skip
+
 if [ -e "$gnu_pdf" ]
 then
     echo "temporary output file '$gnu_pdf' already exists" >&2
diff --git a/tmac/tests/pdfpic_falls-back-to-PSPIC.sh 
b/tmac/tests/pdfpic_falls-back-to-PSPIC.sh
index 8082a309..31983d03 100755
--- a/tmac/tests/pdfpic_falls-back-to-PSPIC.sh
+++ b/tmac/tests/pdfpic_falls-back-to-PSPIC.sh
@@ -19,9 +19,8 @@
 #
 
 groff="${abs_top_builddir:-.}/test-groff"
-gnu_eps="${abs_top_builddir:-.}/gnu.eps"
-gnu_pdf="${abs_top_builddir:-.}/gnu-fallback-pspic.pdf"
-gnu_fallback_eps="${abs_top_builddir:-.}/gnu-fallback-pspic.eps"
+# Give the output a name that won't collide with another test.
+gnu_pdf="${abs_top_builddir:-.}/doc/gnu-fallback-pspic.pdf"
 
 if ! command -v gs >/dev/null
 then
@@ -29,6 +28,23 @@ then
     exit 77 # skip
 fi
 
+# Locate directory containing our test artifacts.
+artifact_dir=
+
+for buildroot in . .. ../..
+do
+    d=$buildroot/doc
+    if [ -f $d/gnu.eps ]
+    then
+        artifact_dir=$d
+        gnu_eps=$artifact_dir/gnu.eps
+        break
+    fi
+done
+
+# If we can't find it, we can't test.
+test -z "$artifact_dir" && exit 77 # skip
+
 if [ -e "$gnu_pdf" ]
 then
     echo "temporary output file '$gnu_pdf' already exists" >&2
@@ -51,7 +67,7 @@ fi
 test -z $fail \
     && printf '%s\n' "$input" | "$groff" -Tps -U -z || fail=YES
 
-rm -f "$gnu_pdf" "$gnu_fallback_eps"
+rm -f "$gnu_pdf"
 test -z $fail
 
 # vim:set ai et sw=4 ts=4 tw=72: