[groff] 01/01: man pages: Escape interpolated Make variables.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f61089db04816e30cc9045988a4c80f84d0350d7
Author: G. Branden Robinson <address@hidden>
Date:   Sat Nov 10 10:00:01 2018 -0500

    man pages: Escape interpolated Make variables.
    
        * makevarescape.sed: Transform - to \-, ~ to \(ti, and so forth,
        (with an extra layer of backslashes--see below) so that Makefile
        variables containing ASCII characters that do not represent
        themselves literally in *roff (see groff_char(7)) are correctly
        interpolated into man page text.
    
        * Makefile.am (.man): Transform Makefile variables with the
        above script when interpolating them into man page text.
    
        Note that while the script, combined with this target, will
        transform ` to \(ga, including grave accents in Makefile
        variables is likely to fail when the shell lexes the argument to
        echo within the old-style command substitution ``.  Testing
        shows that grave accents should work[1] if POSIX-style command
        substitution $() is done instead.  However, $() is less
        portable.  (Triple-escaping grave accents \\\` inside the
        interpolated Makefile variable will work, but is not attempted
        at present.)
    
        Note also that the amount of backslash-escaping in the sed
        script is excessive (and incorrect) for normal purposes, but
        required here because a command substitution is being nested
        inside yet another invocation of sed.
    
        [1] For this target; no assurances about the good behavior of
        unusual characters in Makefile variables in other aspects of the
        groff build are offered.
    
        Fixes <https://savannah.gnu.org/bugs/index.php?55004>.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 ChangeLog         | 34 +++++++++++++++++++++++++++++++
 Makefile.am       | 60 ++++++++++++++++++++++++++++++++++++++-----------------
 makevarescape.sed |  6 ++++++
 3 files changed, 82 insertions(+), 18 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 23138cf..ddf682a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,37 @@
+2018-11-10  G. Branden Robinson <address@hidden>
+
+       man pages: Escape interpolated Make variables.
+
+       * makevarescape.sed: Transform - to \-, ~ to \(ti, and so forth,
+       (with an extra layer of backslashes--see below) so that Makefile
+       variables containing ASCII characters that do not represent
+       themselves literally in *roff (see groff_char(7)) are correctly
+       interpolated into man page text.
+
+       * Makefile.am (.man): Transform Makefile variables with the
+       above script when interpolating them into man page text.
+
+       Note that while the script, combined with this target, will
+       transform ` to \(ga, including grave accents in Makefile
+       variables is likely to fail when the shell lexes the argument to
+       echo within the old-style command substitution ``.  Testing
+       shows that grave accents should work[1] if POSIX-style command
+       substitution $() is done instead.  However, $() is less
+       portable.  (Triple-escaping grave accents \\\` inside the
+       interpolated Makefile variable will work, but is not attempted
+       at present.)
+
+       Note also that the amount of backslash-escaping in the sed
+       script is excessive (and incorrect) for normal purposes, but
+       required here because a command substitution is being nested
+       inside yet another invocation of sed.
+
+       [1] For this target; no assurances about the good behavior of
+       unusual characters in Makefile variables in other aspects of the
+       groff build are offered.
+
+       Fixes <https://savannah.gnu.org/bugs/index.php?55004>.
+
 2018-11-07  Bertrand Garrigues <address@hidden>
 
        Add a sanity check on 2 hdtbl examples.
diff --git a/Makefile.am b/Makefile.am
index 65bfe90..f95bf1c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -877,37 +877,61 @@ MOSTLYCLEANFILES += $(prefixexecbin_SCRIPTS) 
$(bin_SCRIPTS) \
 # Suffix rule to build .1, .5 and .7 files from .1.man, .5.man and
 # .7.man files.  The brackets around the @ are used to prevent the
 # substitution of the variable by automake.
+#
+# The sed script transforms - to \-, ~ to \(ti, and so forth, (with an
+# extra layer of backslashes--see below) so that Makefile variables
+# containing ASCII characters that do not represent themselves literally
+# in *roff (see groff_char(7)) are correctly interpolated into man page
+# text.
+#
+# Note that while the script, combined with this target, will transform
+# ` to \(ga, including grave accents in Makefile variables is likely to
+# fail when the shell lexes the argument to echo within the old-style
+# command substitution `` below.  Testing shows that grave accents
+# should work* if POSIX-style command substitution $() is done instead.
+# However, $() is less portable.  (Triple-escaping grave accents \\\`
+# inside the interpolated Makefile variable will work, but is not
+# attempted here.)
+#
+# Note also that the amount of backslash-escaping in the sed script is
+# excessive (and incorrect) for normal purposes, but required here
+# because a command substitution is being nested inside yet another
+# invocation of sed.
+#
+# * For this target; no assurances about the good behavior of unusual
+#   characters in Makefile variables in other aspects of the groff build
+#   are offered.
+makevarescape=$(top_srcdir)/makevarescape.sed
 SUFFIXES += .man
 .man:
        $(AM_V_GEN)rm -f $@ \
        && $(MKDIR_P) `dirname address@hidden \
        && LC_ALL=C \
-        sed -e "s|address@hidden@]|$(appresdir)|g" \
-            -e "s|address@hidden@]|$(bindir)|g" \
-            -e "s|address@hidden@]|$(BROKEN_SPOOLER_FLAGS)|g" \
-            -e "s|address@hidden@]|$(common_words_file)|g" \
-            -e "s|address@hidden@]|$(datasubdir)|g" \
-            -e "s|address@hidden@]|$(indexdir)/$(indexname)|g" \
-            -e "s|address@hidden@]|$(indexname)|g" \
+        sed -e "s|address@hidden@]|`echo $(appresdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(bindir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(common_words_file) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(datasubdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(indexdir)/$(indexname) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(indexname) | sed -f 
$(makevarescape)`|g" \
             -e "s|address@hidden@]|$(DEVICE)|g" \
-            -e "s|address@hidden@]|$(docdir)|g" \
-            -e "s|address@hidden@]|$(exampledir)|g" \
-            -e "s|address@hidden@]|$(fontdir)|g" \
+            -e "s|address@hidden@]|`echo $(docdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(exampledir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(fontdir) | sed -f 
$(makevarescape)`|g" \
             -e "s|address@hidden@]|$(g)|g" \
             -e "address@hidden@]!`echo $(g) | tr '[a-z]' '[A-Z]'`!g" \
-            -e "s|address@hidden@]|$(htmldocdir)|g" \
+            -e "s|address@hidden@]|`echo $(htmldocdir) | sed -f 
$(makevarescape)`|g" \
             -e "s|address@hidden@]|$(indexext)|g" \
-            -e "s|address@hidden@]|$(legacyfontdir)|g" \
-            -e "s|address@hidden@]|$(localfontdir)|g" \
-            -e "s|address@hidden@]|$(localtmacdir)|g" \
-            -e "s|address@hidden@]|$(tmacdir)|g" \
+            -e "s|address@hidden@]|`echo $(legacyfontdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(localfontdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(localtmacdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(tmacdir) | sed -f 
$(makevarescape)`|g" \
             -e "s|address@hidden@]|$(man1ext)|g" \
             -e "s|address@hidden@]|$(man5ext)|g" \
             -e "s|address@hidden@]|$(man7ext)|g" \
             -e "s|address@hidden@]|`$(PERL) $(top_srcdir)/mdate.pl $<`|g" \
-            -e "s|address@hidden@]|$(oldfontdir)|g" \
-            -e "s|address@hidden@]|$(pdfdocdir)|g" \
-            -e "s|address@hidden@]|$(systemtmacdir)|g" \
+            -e "s|address@hidden@]|`echo $(oldfontdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(pdfdocdir) | sed -f 
$(makevarescape)`|g" \
+            -e "s|address@hidden@]|`echo $(systemtmacdir) | sed -f 
$(makevarescape)`|g" \
             -e "s|address@hidden@]|$(tmac_an_prefix)|g" \
             -e "s|address@hidden@]|$(tmac_m_prefix)|g" \
             -e "s|address@hidden@]|$(tmacdir)/mm|g" \
diff --git a/makevarescape.sed b/makevarescape.sed
new file mode 100644
index 0000000..54f5513
--- /dev/null
+++ b/makevarescape.sed
@@ -0,0 +1,6 @@
+s/\\/\\\\e/g
+s/'/\\\\(aq/g
+s/-/\\\\&/g
+s/\^/\\\\(ha/g
+s/`/\\\\(ga/g
+s/~/\\\\(ti/g