[groff] 04/11: doc/doc.am: Refactor to drop unused `DOC_GROFF`.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b8efdbbd82f813b57fd4c6dedeb7b5aa19053a21
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Mar 23 19:08:10 2022 +1100

    doc/doc.am: Refactor to drop unused `DOC_GROFF`.
    
    * doc/doc.am: Refactor.  Drop ghastly hack used to get file names into
      troff diagnostics when reading from standard input.  We've refactored
      so that it no longer does, making the hack unnecessary.  For the same
      reason, no users of the `DOC_GROFF` macro remain, so delete it.  Add
      comments to explain what `DOC_SED` and `DOC_GROFF_ONLY` are for.
    
    Thanks to Ingo Schwarze for the discussion.
---
 ChangeLog  |  9 +++++++++
 doc/doc.am | 23 ++++++++---------------
 2 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 0e4ee7eb..e8ee61de 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -13,6 +13,15 @@
 
 2022-04-05  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       * doc/doc.am: Refactor.  Drop ghastly hack used to get file
+       names into troff diagnostics when reading from standard input.
+       We've refactored so that it no longer does, making the hack
+       unnecessary.  For the same reason, no users of the `DOC_GROFF`
+       macro remain, so delete it.  Add comments to explain what
+       `DOC_SED` and `DOC_GROFF_ONLY` are for.
+
+2022-03-29  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        * doc/doc.am: Refactor.
        (doc/pic.html, doc/webpage.html): Drop indirection of source
        document through `DOC_SED` macro.  It was not necessary since
diff --git a/doc/doc.am b/doc/doc.am
index 0998d8c9..90415aa7 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -21,10 +21,18 @@
 doc_srcdir = $(abs_top_srcdir)/doc
 doc_builddir = $(abs_top_builddir)/doc
 
+# Some document sources are parameterized in configuration options like
+# the groff version number and the command prefix.  Use this in target
+# rules to prepare formattable versions of them from .in files.
 DOC_SED = $(SED) \
   -e "s;[@]VERSION[@];$(VERSION);" \
   -e "s;[@]g[@];$(g);g;"
 
+# Use this in target rules to run the build tree's groff.
+#
+# It includes flags to locate its tmac and device/font description
+# directories and to produce verbose diagnostics in the event of syntax
+# or formatting problems.
 DOC_GROFF_ONLY=\
   GROFF_COMMAND_PREFIX= \
   GROFF_BIN_PATH="$(GROFF_BIN_PATH)" \
@@ -34,21 +42,6 @@ DOC_GROFF_ONLY=\
 # 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.
-#
-# Use the POSIX shell $'\n' feature when all platforms of interest
-# support it.
-#
-#DOC_GROFF = $(DOC_SED) -e 1i\$$'\n'".lf 1 $<"$$'\n' $< \
-#      | $(DOC_GROFF_ONLY)
-#
-# In the meantime, a shell variable must be prepared in each target rule
-# shell command using $(DOC_SED).  This solution is adapted from the GNU
-# Autoconf manual, "Newlines in Make Rules".
-DOC_GROFF = nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \
-         $(DOC_SED) -e "1i\\$$nl.lf 1 $<$$nl" $< | $(DOC_GROFF_ONLY)
-
 # Other doc, installed in $(docdir)
 if BUILD_OTHERDOC
 # Files located in the source tree