[groff] 01/01: Fix Savannah bug #44784

[Bertrand Garrigues]

bgarrigues pushed a commit to branch master
in repository groff.

commit f8841ccea00a1bebd825365156897b707f82ccec
Author: Peter Bray <address@hidden>
Date:   Wed Jul 1 00:25:04 2015 +0200

    Fix Savannah bug #44784
    
    Compatibility Mode rendering of groff manual pages
    
    * m4/groff.m4 (GROFF_WITH_COMPATIBILITY_WRAPPERS): New macro to
    implement 'configure' option
    '--with-compatibility-wrappers=<value>'.  With this option the
    user can control how groff compatibility wrappers for
    vendor-provided non-GNU macro sets are installed.
    
    * configure.ac: Use new macro GROFF_WITH_COMPATIBILITY_WRAPPERS.
    
    * Makefile.am: Define tmac_*_prefix if 'compatibility_wrappers' is
    set to 'yes'.
    
    * tmac/tmac.am: Use 'compatibility_wrappers' to control the
    installation:
    
    - If set to `no', the groff-provided macro set are installed in
    <prefix>/share/groff/<version>/tmac/ with the original macro set
    name.
    
    - If set to `yes', the groff-provided macro set are installed in
    <prefix>/share/groff/<version>/tmac/ with a prefix of
    $(tmac_prefix) (which is usually `g') and the generated
    compatibility wrappers are installed in
    <prefix>/lib/groff/site-tmac, with the original macro set name.
    
    - If set to `manual', the groff-provided macro set are installed
    in <prefix>/share/groff/<version>/tmac/ with the original macro
    set name and the generated compatibility wrappers are installed in
    <prefix>/lib/groff/site-tmac, with a name of
    <macro><wrapper_suffix> (which is usually `-os').
---
 ChangeLog    |   36 ++++++++++++++
 Makefile.am  |   47 ++++++++++++++++--
 NEWS         |    8 +++
 configure.ac |    1 +
 m4/groff.m4  |  154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 tmac/tmac.am |   89 +++++++++++++++++++++++-----------
 6 files changed, 302 insertions(+), 33 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 21f597f..6951dcf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,39 @@
+2015-07-01 Peter Bray <address@hidden>
+
+       Fix Savannah bug #44784
+
+       Compatibility Mode rendering of groff manual pages
+
+       * m4/groff.m4 (GROFF_WITH_COMPATIBILITY_WRAPPERS): New macro to
+       implement 'configure' option
+       '--with-compatibility-wrappers=<value>'.  With this option the
+       user can control how groff compatibility wrappers for
+       vendor-provided non-GNU macro sets are installed.
+
+       * configure.ac: Use new macro GROFF_WITH_COMPATIBILITY_WRAPPERS.
+
+       * Makefile.am: Define tmac_*_prefix if 'compatibility_wrappers' is
+       set to 'yes'.
+
+       * tmac/tmac.am: Use 'compatibility_wrappers' to control the
+       installation:
+
+       - If set to `no', the groff-provided macro set are installed in
+       <prefix>/share/groff/<version>/tmac/ with the original macro set
+       name.
+
+       - If set to `yes', the groff-provided macro set are installed in
+       <prefix>/share/groff/<version>/tmac/ with a prefix of
+       $(tmac_prefix) (which is usually `g') and the generated
+       compatibility wrappers are installed in
+       <prefix>/lib/groff/site-tmac, with the original macro set name.
+
+       - If set to `manual', the groff-provided macro set are installed
+       in <prefix>/share/groff/<version>/tmac/ with the original macro
+       set name and the generated compatibility wrappers are installed in
+       <prefix>/lib/groff/site-tmac, with a name of
+       <macro><wrapper_suffix> (which is usually `-os').
+
 2015-06-17  Werner LEMBERG  <address@hidden>
 
        * tmac/tty.tmac: Fix mapping of \[bu] character for -Tutf8.
diff --git a/Makefile.am b/Makefile.am
index 6ece629..d3b9de7 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -228,20 +228,57 @@ 
tmacpath=$(systemtmacdir)$(RT_SEP)$(localtmacdir)$(RT_SEP)$(tmacdir)
 # in the groff macro directory that references the system macro
 # package.
 
-# If there is a groff version of a macro package listed in $(tmac_wrap),
-# then the groff version will be installed with a prefix of this.
+# compatibility_wrappers
+# (groff compatibility wrappers for vendor-provided non-GNU macro sets)
+#
+# `compatibility_wrappers' controls the creation and installation of
+# compatibility wrappers for the macro sets named in `tmac_wrap'.
+# Its value must be one of:
+#   `yes'    install compatibility wrappers as the original macro set name
+#            (that is, the default implementation of that macro set), and
+#            install the groff implementation with a prefix (usually g).
+#   `no'     do not install compatibility wrappers; only install the groff
+#            implementation of each macro set.
+#   `manual' install the compatibility wrappers as `<macro>-os' and install
+#            the groff implementation of each macro set as the default
+#            implementation of that macro set.
+
+# Don't make this empty.
+wrapper_suffix_default="-os"
+
+wrapper_suffix=`if test $(compatibility_wrappers) = manual; then echo 
$(wrapper_suffix_default); fi`
+
+# When `compatibility_wrappers' is `yes', if there is a groff implementation
+# of a macro set listed in $(tmac_wrap), then the groff implementation will be
+# installed with a prefix of $(tmac_prefix) via the collision detection
+# variables $(tmac_m_prefix), $(tmac_s_prefix), and $(tmac_an_prefix).
+
 # Don't make this empty.
 tmac_prefix=g
 
 # The groff -mm macros will be available as -m$(tmac_m_prefix)m.
 tmac_m_prefix=\
- `for i in $(tmac_wrap) ""; do case "$$i" in m) echo $(tmac_prefix);; esac; 
done`
+ `if test $(compatibility_wrappers) = yes; then \
+    for i in $(tmac_wrap) ""; do \
+      case "$$i" in m) echo $(tmac_prefix);; esac; \
+    done; \
+  fi`
+
 # The groff -ms macros will be available as -m$(tmac_s_prefix)s.
 tmac_s_prefix=\
- `for i in $(tmac_wrap) ""; do case "$$i" in s) echo $(tmac_prefix);; esac; 
done`
+ `if test $(compatibility_wrappers) = yes; then \
+    for i in $(tmac_wrap) ""; do \
+      case "$$i" in s) echo $(tmac_prefix);; esac; \
+    done; \
+  fi`
+
 # The groff -man macros will be available as -m$(tmac_an_prefix)an.
 tmac_an_prefix=\
- `for i in $(tmac_wrap) ""; do case "$$i" in an) echo $(tmac_prefix);; esac; 
done`
+ `if test $(compatibility_wrappers) = yes; then \
+    for i in $(tmac_wrap) ""; do \
+      case "$$i" in an) echo $(tmac_prefix);; esac; \
+    done; \
+  fi`
 
 # Extension to be used for refer index files.  Index files are not
 # sharable between different architectures, so you might want to use
diff --git a/NEWS b/NEWS
index eeb4090..0085f47 100644
--- a/NEWS
+++ b/NEWS
@@ -84,6 +84,14 @@ o In -mdoc, command %C is now available, providing a city or 
place
   reference.
 
 
+Miscellaneous
+-------------
+
+o New 'configure' option --with-compatibility-wrappers to control how groff
+  compatibility wrappers for vendor-provided non-GNU macro sets are installed
+  (See: ./configure --help).
+
+
 VERSION 1.22.2
 ==============
 
diff --git a/configure.ac b/configure.ac
index e25548f..981be01 100644
--- a/configure.ac
+++ b/configure.ac
@@ -166,6 +166,7 @@ GROFF_BROKEN_SPOOLER_FLAGS
 GROFF_PAGE
 GROFF_G
 GROFF_TMAC
+GROFF_WITH_COMPATIBILITY_WRAPPERS
 GROFF_TARGET_PATH_SEPARATOR
 GROFF_HTML_PROGRAMS
 GROFF_PDFDOC_PROGRAMS
diff --git a/m4/groff.m4 b/m4/groff.m4
index 7d9350a..75049e6 100644
--- a/m4/groff.m4
+++ b/m4/groff.m4
@@ -919,6 +919,160 @@ AC_DEFUN([GROFF_G],
    fi
    AC_SUBST([g])])
 
+# Controllable groff compatibility wrappers for vendor-provided macro sets
+#
+#   Background
+#
+#     groff's configure script checks for a non-GNU system troff implementation
+#     in GROFF_G above, and uses this to rename programs that would conflict
+#     with the system *roff implementation. On such systems, groff's version of
+#     troff is installed as gtroff, groff's version of nroff is installed as
+#     gnroff, and so forth. See the ENVIRONMENT section of groff(1)'s manual
+#     page for the entry on GROFF_COMMAND_PREFIX, and the SEE ALSO section for
+#     details. The implementation of this can be found in "We use Automake's
+#     Uniform Naming Scheme" in Makefile.am, and its use of NAMEPREFIX.
+#
+#     groff's configure script also checks for vendor-provided macro sets in
+#     GROFF_TMAC above, which sets 'sys_tmac_prefix' to the location of any
+#     vendor-provided macro sets. The script then determines if any of these
+#     vendor-provided macro sets are non-GNU implementations. A space-separated
+#     list of macro sets requiring compatibility wrappers is stored in
+#     'tmac_wrap'.
+#
+#     If 'tmac_wrap' is a non-empty list, the make infrastructure will build
+#     groff compatibility wrappers in the 'tmac' directory for each mentioned
+#     macro set. These wrappers enable compatibility mode (.cp 1) and include
+#     (.so <filepath>) the vendor implementation of that macro set. The 'an'
+#     wrapper gets special treatment, by including the 'andoc.tmac' macro set,
+#     before loading the vendor implementation.
+#
+#     In groff version 1.22.3 and prior, if 'tmac_wrap' is a non-empty list at
+#     installation time (make install), the groff compatibility wrappers are
+#     installed in '<prefix>/lib/groff/site-tmac' directory (technically
+#     'systemtmacdir' in Makefile.am) as the base macro set name (example:
+#     an.tmac), and the groff implementation of these macro sets are installed
+#     with a 'g' prefix in the '<prefix>/share/groff/<version>/tmac' directory
+#     (example: gan.tmac).
+#
+#     If your system has these compatibility wrappers installed, then the
+#     command 'groff -man ...' (as an example) uses your vendor's 'an' macro
+#     set in compatibility mode, while the command 'groff -mgan ...' uses the
+#     groff implementation of the 'an' macro set.
+#
+#     With groff being the principal (but not the only) full-featured *roff
+#     implementation in use today, and most FLOSS UNIX-like Operating Systems
+#     using groff as their *roff implementation, the automatic implementation
+#     of compatibility wrappers on systems having their own macro sets needs to
+#     be revisited. Most FLOSS software is now developed on systems having no
+#     other *roff implementation, so manual pages (for example) are developed
+#     and proofread on systems using groff's implementation of the 'an' macro
+#     set.
+#
+#     On systems with their own macro sets (especially 'an'), documents can be
+#     rendered incorrectly from the document author's point of view, when
+#     these compatibility mode wrappers are used. groff's own manual pages are
+#     the perfect case in point, with most not showing the principal usage line
+#     of a command, due to the use of .SY/.OP/.YS macros to display such lines.
+#
+#   Updating groff's use of compatibility mode wrappers
+#
+#     Given the above, on systems with their own (non-GNU) macro sets, groff's
+#     AUTOMATIC installation of these generated vendor compatibility wrappers
+#     as the principal implementation of a macro set for groff(1) users may not
+#     be desirable, especially if the users are principally using groff(1) to
+#     format FLOSS manual pages.
+#
+#     The '--with-compatibility-wrappers=<value>' option to 'configure' gives
+#     these systems control over the default macro set implementation in use
+#     when using the groff family of tools.
+#
+#     The supported values of the '--with-compatibility-wrappers=<value>'
+#     option are:
+#       'check'  [default] Check if system has vendor-provided non-GNU
+#                implementation of any *roff macro set. Based on that use the
+#                'yes' or 'no' value for '--with-compatibility-wrappers'. This
+#                effectively emulates prior groff releases' implementation.
+#       'yes'    Install the vendor compatibility wrappers as groff's default
+#                implementation of these macro sets. This is compatible with
+#                groff implementations up to and including version 1.22.3.
+#                Direct use of the 'yes' option is discouraged, as it will
+#                abort the configure process if no vendor-provided non-GNU
+#                macro set implementations exists.
+#       'no'     Do not install any vendor compatibility wrappers. Use the
+#                groff implementation of all macro sets as the default.
+#       'manual' Install the vendor compatibility wrappers as '<macro>-os.tmac'
+#                in the same directory as 'yes' option ('systemtmacdir').
+#                groff users can access the vendor-provided macro set via the
+#                '-m<macro>-os' option on the command line of a tool from the
+#                groff family. The naming of the option value reflects that now
+#                a manual step must be taken to use the vendor-provided
+#                implementation of the macro set. This option can safely be
+#                used on systems without vendor-provided non-GNU macro set
+#                implementations to allow for cross-platform build
+#                instructions.
+#
+
+AC_DEFUN([GROFF_WITH_COMPATIBILITY_WRAPPERS],
+  [AC_ARG_WITH([compatibility-wrappers],
+    [AS_HELP_STRING([--with-compatibility-wrappers[[=VALUE]]],
+      [choose whether and how groff compatibility wrappers for \
+       vendor-provided non-GNU macro sets are installed. VALUE can be \
+       `check', `yes', `no' or `manual'. \
+       `check' (the default) checks for the existence of vendor-provided \
+       non-GNU macro sets, and implements the `yes' or `no' option \
+       accordingly. \
+       `yes' generates compatibility wrappers for vendor-provided non-GNU \
+       macro sets to allow their use with groff-based tools. The \
+       compatibility wrappers are installed with the original macro set name, \
+       while groff implementation of these macro sets are installed with a \
+       `g' prefix. Thus use of the groff implementation of these macro sets \
+       requires use of the `-mg<macro>' option (example: -mgan). \
+       `no' only installs the groff implementation of macro sets. \
+       `manual' generates compatibility wrappers for vendor-provided non-GNU \
+       macro sets as `<macro>-os'. Use of these groff compatibility wrappers \
+       (for vendor-provided non-GNU macro sets) requires the use of the \
+       `-m<macro>-os' option (example: -man-os).])],
+    [compatibility_wrappers="$withval"],
+    [compatibility_wrappers="check"])
+
+    if test "x$compatibility_wrappers" != "xcheck"  -a \
+            "x$compatibility_wrappers" != "xyes"    -a \
+            "x$compatibility_wrappers" != "xno"     -a \
+            "x$compatibility_wrappers" != "xmanual"
+    then
+         AC_MSG_WARN([Invalid `--with-compatibility-wrappers' argument: 
`$compatibility_wrappers' - assuming `check' requested.])
+         compatibility_wrappers="check"
+    fi
+
+    if test "x$tmac_wrap" = "x"
+    then
+        # No Operating System Macro Sets Present
+        if   test "x$compatibility_wrappers" = "xcheck"
+        then
+            compatibility_wrappers="no"
+        elif test "x$compatibility_wrappers" = "xyes"
+        then
+            AC_MSG_ERROR([No non-GNU macro sets found - cannot create and 
install compatibility wrappers])
+        elif test "x$compatibility_wrappers" = "xno"
+        then
+            : # No action required
+        elif test "x$compatibility_wrappers" = "xmanual"
+        then
+            # `manual' allows quiet conversion to `no' to support
+            # cross-platform build instructions
+            compatibility_wrappers="no"
+        fi
+    else
+        # One or more Operating System Macro Sets Present
+        if   test "x$compatibility_wrappers" = "xcheck"
+        then
+            compatibility_wrappers="yes"
+        fi
+    fi
+
+    # Now compatibility_wrappers can only be yes, no or manual
+    AC_SUBST([compatibility_wrappers])
+  ])
 
 # We need the path to install-sh to be absolute.
 
diff --git a/tmac/tmac.am b/tmac/tmac.am
index b778d84..e75a558 100644
--- a/tmac/tmac.am
+++ b/tmac/tmac.am
@@ -142,19 +142,45 @@ tmac-dist-hook:
          cp -f $(top_srcdir)/$$f-u $(distdir)/tmac; \
        done
 
-
-# If the system comes with its own tmac macro installation (/usr/lib/tmac
-# contains tmac.an, tmac.m, tmac.s), ms and man macros are installed as
-# gs.tmac and gan.tmac, instead of s.tmac and an.tmac.  Also, an.tmac,
-# m.tmac and s.tmac files are installed in <prefix>/lib/groff/site-tmac.
-all: tmac/stamp-wrap
-
 $(TMACMDOCFILES) $(TMACSTRIPFILES): 
        $(MKDIR_P) $(top_builddir)/tmac
        for f in $(TMACMDOCFILES) $(TMACSTRIPFILES); do \
           sed -f $(tmac_srcdir)/strip.sed $(top_srcdir)/$$f-u > 
$(top_builddir)/$$f; \
        done
 
+tmac/www.tmac: tmac/www.tmac.in
+       $(MKDIR_P) $(top_builddir)/tmac
+       sed -e "s;address@hidden@];$(pnmtops_nosetpage);g" \
+         $(tmac_srcdir)/www.tmac.in > $(top_builddir)/tmac/www.tmac
+
+# The installation of groff compatibility wrappers for vendor-provided non-GNU
+# macro sets is controlled by `compatibility_wrappers' (see the commentary
+# surrounding m4/groff.m4's GROFF_WITH_COMPATIBILITY_WRAPPERS).  Collision
+# detection variables of the form `tmac_<macro>_prefix' are defined in
+# Makefile.am, to assist in the installation of groff-provided macro sets.
+#
+# When `compatibility_wrappers' is `no', one step is performed:
+#   - the groff-provided macro set implementations are installed in
+#     <prefix>/share/groff/<version>/tmac/ with the original macro set name
+#
+# When `compatibility_wrappers' is `yes', two steps are performed:
+#   - the groff-provided macro set implementations are installed in
+#     <prefix>/share/groff/<version>/tmac/ with a prefix of $(tmac_prefix)
+#     (which is usually `g', via the appropriate collision detection variable)
+#   - the generated compatibility wrappers are installed in
+#     <prefix>/lib/groff/site-tmac, with the original macro set name
+#
+# When `compatibility_wrappers' is `manual', two steps are performed:
+#   - the groff-provided macro set implementations are installed in
+#     <prefix>/share/groff/<version>/tmac/ with the original macro set name
+#   - the generated compatibility wrappers are installed in
+#     <prefix>/lib/groff/site-tmac, with a name of <macro><wrapper_suffix>,
+#     (which is usually `-os', see `wrapper_suffix_default' in Makefile.am)
+
+
+all: tmac/stamp-wrap
+
+# Generate groff compatibility wrappers for all non-GNU OS provided macro sets
 tmac/stamp-wrap:
        $(MKDIR_P) $(top_builddir)/tmac;
        if test -n "$(tmac_wrap)"; then \
@@ -169,40 +195,47 @@ tmac/stamp-wrap:
        fi
        touch $@
 
-tmac/www.tmac: tmac/www.tmac.in
-       $(MKDIR_P) $(top_builddir)/tmac
-       sed -e "s;address@hidden@];$(pnmtops_nosetpage);g" \
-         $(tmac_srcdir)/www.tmac.in > $(top_builddir)/tmac/www.tmac
-
+# Install groff compatibility wrappers into <prefix>/lib/groff/site-tmac
 install-data-local: install_tmac_wrap
 install_tmac_wrap:
        $(MKDIR_P) $(DESTDIR)$(systemtmacdir);
-       if test -n "$(tmac_wrap)"; then \
-         for m in ""$(tmac_wrap); do \
-           $(INSTALL_DATA) $(tmac_builddir)/$$m-wrap \
-              $(DESTDIR)$(systemtmacdir)/$$m.tmac; \
-         done; \
+       if test "$(compatibility_wrappers)" != "no"; then \
+         if test -n "$(tmac_wrap)"; then \
+           for m in ""$(tmac_wrap); do \
+             $(INSTALL_DATA) $(tmac_builddir)/$$m-wrap \
+                $(DESTDIR)$(systemtmacdir)/$$m$(wrapper_suffix).tmac; \
+           done; \
+         fi; \
        fi
 
+# Rename the groff implementations of colliding macro sets to have a prefix
 install-data-hook: install_tmac_wrap_hook
 install_tmac_wrap_hook:
-       if test -n "$(tmac_wrap)"; then \
-         if test -f $(DESTDIR)$(tmacdir)/s.tmac; then \
-           mv $(DESTDIR)$(tmacdir)/s.tmac \
-             $(DESTDIR)$(tmacdir)/$(tmac_s_prefix)s.tmac; \
-         fi; \
-         if test -f $(DESTDIR)$(tmacdir)/an.tmac; then \
-           mv $(DESTDIR)$(tmacdir)/an.tmac \
-             $(DESTDIR)$(tmacdir)/$(tmac_an_prefix)an.tmac; \
+       if test "$(compatibility_wrappers)" = "yes"; then \
+         if test -n "$(tmac_wrap)"; then \
+           if test -f $(DESTDIR)$(tmacdir)/s.tmac -a -n "$(tmac_s_prefix)"; \
+           then \
+             mv $(DESTDIR)$(tmacdir)/s.tmac \
+                $(DESTDIR)$(tmacdir)/$(tmac_s_prefix)s.tmac; \
+           fi; \
+           if test -f $(DESTDIR)$(tmacdir)/an.tmac -a -n "$(tmac_an_prefix)"; \
+           then \
+             mv $(DESTDIR)$(tmacdir)/an.tmac \
+                $(DESTDIR)$(tmacdir)/$(tmac_an_prefix)an.tmac; \
+           fi; \
          fi; \
        fi
 
+# Uninstall groff compatibility wrappers & renamed groff implementation
+# macro sets
 uninstall_groffdirs: uninstall_tmac_hook
 uninstall_tmac_hook:
        if test -n "$(tmac_wrap)"; then \
-         for m in ""$(tmac_wrap); do \
-           $(RM) $(DESTDIR)$(systemtmacdir)/$$m.tmac; \
-         done; \
+         if test "$(compatibility_wrappers)" != "no"; then \
+           for m in ""$(tmac_wrap); do \
+             $(RM) $(DESTDIR)$(systemtmacdir)/$$m$(wrapper_suffix).tmac; \
+           done; \
+         fi; \
          $(RM) -f $(DESTDIR)$(tmacdir)/$(tmac_an_prefix)an.tmac; \
          $(RM) -f $(DESTDIR)$(tmacdir)/$(tmac_s_prefix)s.tmac; \
        fi