file #34156:  with-compatibility-wrappers-revision-1.patch

TODO:  s/-with-compatibility-mode/--with-compatibility-wrappers/

I have just noticed that in two places in the comments (nothing the end user sees) the older name '--with-compatibility-mode' is used, instead of the newer '--with-compatibility-wrappers'. I'll fix this along with any other reviewer comments once I get a committer to work with.

Werner,

  I thought you had reviewed the changes (comment #9), so do I just need to ask for someone with commit access to integrate the previously supplied code?

With that task being, review and commit the patch (#33630), review the provided notes (#33629), and add a Changelog entry.

file #33629:  patch-notes.txt
file #33630:  with-compatibility-wrappers.patch

Correct?

Regards,
Peter

PS: I realise the bug report goes into other issues which are not covered by the supplied code, but they are basically a side-effect of not using the groff provided macros (fixable by use of the supplied code) and consistency observations on the manual pages themselves (which don't have to be fixed, provided the user uses groff supplied macros)

Greetings,

The FSF file-copy copyright assignment form has been sent to Werner, I included the following PS, which I thought should go in the bug history:

PS: You may wish to note in the release notes, that groff manual pages require groff manual page ('an') macros to render correctly. Thus those platforms with non-GNU vendor provided 'an' macros, who do not choose the new --with-compatibility-mode=manual, may find that the groff manual pages do not render as the author intended, due to missing macro definitions.

Additionally, I have the following thoughts:

 - the work done to support compatibility mode,
    https://savannah.gnu.org/bugs/?44708
that is, shortening all the macro names to two characters, could possibly be reversed (this is definitely not my call, I don't have any knowledge of macro compatibility, but the longer names definitely are easier to read)

  - I recall, without actually revisiting the manual pages themselves, that some groff manual pages redefined macros that were in the groff-provided 'an' macro set, BUT ONLY SOME, so on systems not using groff-provided 'an' macros the rendering of groff man pages will be hit and miss. I recall the macros have to do with command options, a critical set of macros for getting the correct SYNOPSIS rendering.

  - The last point does bring up a 'lint' type issue, maybe these (repeated) macro definitions should be removed from the manual pages they have been coded into, so that only a single definition of the macro exists within the project (for 'an' / 'andoc' macro sets, obviously other macro sets can reuse macro names). Maybe a tool exists to do this 'lint' style work, I have not investigated this. But the following is a starting point:

% find . -type f -name \*.man | xargs egrep -h '^\. de[^ ] ' | sort | uniq -c | sort -n | tail
   2 .    de C\\$1
   2 .  de make-C-macro
   2 .de FONT
   2 .de LI
   3 .de FT
   6 .de TQ
   9 .de OP
  17 .de Tp
  31 .de au
  57 .de co

See the original post in the bug report regarding .SY/.OP/.YS and related macro definitions (partly reproduced below). But please remember that I am not familiar with *roff macro definitions, so the above may be perfectly fine (such as unique author definitions), but at least simplistically that seems like some repeated code.

Following on from that, it would seem better to have groff specific manual page macros defined in a single location and expanded into the actual manual pages at build time. I believe that could be done with soelim(1) as part of the build process.

Just the thoughts of a casual observer without *roff knowledge,

Peter

Repeated Content from the original posting:

Looking at the raw source again, I discovered that the .SY/.OP/.YS macros used by the first synopsis line where not being rendered. In the groff manual pages, there are 34 files that use (*1) .OP (for example), while only 9 files that define (*2) the OP macro. I then looked at the two renderings (-man and -mgan) in a postscript viewer for "missing content" on the grog(1) manual page and also noticed that email addresses in the author section were missing, which the source suggested was the rendering of the .MT macro. The stats for .MT are 33 files that use and 0 files that define. The command (*3) shows inconsistencies in the arguments provided to the .MT macro, including occasional quoting of '-' as in '\-' and occasional use of '\:' after an '@' as in '@\:', I wondered if the later were from texinfo source documentation where '@' is special. Finally I noticed that examples in '-mgan' used a typewriter style font (Courier?), but that is was absent from the '-man' output, seems to be related to .EX or maybe .IP or .RS (not investigated further).

*1: find .../share/man/man -type f | xargs grep -l '^.OP' | wc -l
*2: find .../share/man/man -type f | xargs grep -l '^.de.*OP' | wc -l
*3: find .../share/man/man -type f | xargs grep -h '^\.MT' | sort | uniq -c

Greetings,

The provided patch adds the configure option
--with-compatibility-wrappers, which allows the builder of groff on
systems with non-GNU *roff macro sets (such as Solaris 10) to control
the installation of groff compatibility wrappers for the OS provided
macro sets. The name compatibility wrappers was chosen (over the
originally mentioned compatibility mode) as it better reflects the
intent of the option, the option itself is not about groff's
compatibility mode (.cp), but the installation of compatibility
wrappers for OS provided macro sets.

The default value of this new option is "check" which preserves
groff's existing behavior on systems with OS provided macro sets, and
I would assume, but have not tested, the default behavior on systems
without such macro sets. The patch has not been tested on systems
without vendor provided macros, but as most developers and maintainers
will have such systems, it should be tested quite quickly. As noted in
the comments, the value "yes" on systems without such vendor provided
macros, will cause configure to abort. Test System: Solaris 10 X86_64
with gnu tool chain, including gcc-4.1.2, autoconf-2.69 and
automake-1.14.1.

As discussed in the initial write-up, this default behavior is
probably not desirable in 2015 as the UNIX/POSIX?Linux world is
dominated by FLOSS implementations of tools, rather than the
traditional vendor implementations. I would support changing the
default to "manual", but that is not my call.

This patch does not address the issue that groff manual pages do not
rendering correctly via man(1) on Solaris 10 systems, which uses a
vendor provided *roff implementation and macro sets.

The submission is more comments than code, but hopefully that will
mean that all who wonder that way in the future will have a guide ;-)

Regards,
Peter Bray
Sydney, Australia

PS: This patch is submitted in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. I hereby donate
it to the groff project, to do with as the maintainer(s) see fit,
including distribution under any license or licenses they deem fit,
now or in the future. Copyright may be assigned as the maintainer(s)
see fit. It yours!

PPS:
The following shows the "Only in ..." output of a GNU diff comparison
of the installation of groff (Git 2015/04/10) plus the provided patch
for different values of the --with-compatibility-wrappers, where the
value "default" implies the argument was not provided, and thus
defaults to "check", which on this Solaris 10 system, will result in
an effective value of "yes".

% cd /pkgs/64-bit/release
% gdiff -rq groff-git_2015_04_10-{default,yes} | grep -v differ | sort
<No Output>

Commentary:  Expected as default and yes are equivalent on this system>

% gdiff -rq groff-git_2015_04_10-{yes,no} | grep -v differ | sort
Only in groff-git_2015_04_10-no/share/groff/1.22.3/tmac: an.tmac
Only in groff-git_2015_04_10-no/share/groff/1.22.3/tmac: m.tmac
Only in groff-git_2015_04_10-no/share/groff/1.22.3/tmac: mm.tmac
Only in groff-git_2015_04_10-no/share/groff/1.22.3/tmac: mmse.tmac
Only in groff-git_2015_04_10-no/share/groff/1.22.3/tmac: mse.tmac
Only in groff-git_2015_04_10-no/share/groff/1.22.3/tmac: s.tmac
Only in groff-git_2015_04_10-no/share/groff/current/tmac: an.tmac
Only in groff-git_2015_04_10-no/share/groff/current/tmac: m.tmac
Only in groff-git_2015_04_10-no/share/groff/current/tmac: mm.tmac
Only in groff-git_2015_04_10-no/share/groff/current/tmac: mmse.tmac
Only in groff-git_2015_04_10-no/share/groff/current/tmac: mse.tmac
Only in groff-git_2015_04_10-no/share/groff/current/tmac: s.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: an.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: ansun.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: bib.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: m.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: s.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: v.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: vgrind.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gan.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gm.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gmm.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gmmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gs.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gan.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gm.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gmm.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gmmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gs.tmac

Commentary:
  - "no" shows that no prefix was used on the groff macro implementations
  - "yes" shows that "g" prefix was used on the groff macro implementations
     and the installation of the compatibility wrappers in .../site-tmac

% gdiff -rq groff-git_2015_04_10-{yes,manual} | grep -v differ | sort 
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: an-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: ansun-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: bib-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: m-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: s-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: v-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: vgrind-os.tmac
Only in groff-git_2015_04_10-manual/share/groff/1.22.3/tmac: an.tmac
Only in groff-git_2015_04_10-manual/share/groff/1.22.3/tmac: m.tmac
Only in groff-git_2015_04_10-manual/share/groff/1.22.3/tmac: mm.tmac
Only in groff-git_2015_04_10-manual/share/groff/1.22.3/tmac: mmse.tmac
Only in groff-git_2015_04_10-manual/share/groff/1.22.3/tmac: mse.tmac
Only in groff-git_2015_04_10-manual/share/groff/1.22.3/tmac: s.tmac
Only in groff-git_2015_04_10-manual/share/groff/current/tmac: an.tmac
Only in groff-git_2015_04_10-manual/share/groff/current/tmac: m.tmac
Only in groff-git_2015_04_10-manual/share/groff/current/tmac: mm.tmac
Only in groff-git_2015_04_10-manual/share/groff/current/tmac: mmse.tmac
Only in groff-git_2015_04_10-manual/share/groff/current/tmac: mse.tmac
Only in groff-git_2015_04_10-manual/share/groff/current/tmac: s.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: an.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: ansun.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: bib.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: m.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: s.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: v.tmac
Only in groff-git_2015_04_10-yes/lib/groff/site-tmac: vgrind.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gan.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gm.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gmm.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gmmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/1.22.3/tmac: gs.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gan.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gm.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gmm.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gmmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gmse.tmac
Only in groff-git_2015_04_10-yes/share/groff/current/tmac: gs.tmac

Commentary:
  - "manual" shows that no prefix was used on the groff macro implementations
    and that the compatibility wrappers in .../site-tmac have an "-os" suffix
  - "yes" shows that "g" prefix was used on the groff macro implementations
     and the installation of the compatibility wrappers in .../site-tmac

% gdiff -rq groff-git_2015_04_10-{no,manual} | grep -v differ | sort 
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: an-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: ansun-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: bib-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: m-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: s-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: v-os.tmac
Only in groff-git_2015_04_10-manual/lib/groff/site-tmac: vgrind-os.tmac

Commentary:
  - "manual" shows that the compatibility wrappers in .../site-tmac have an
    "-os" suffix, and that otherwise the installation does not differ from "no"


(file #33629, file #33630)

Also needs modification: contrib/mm/mm.am

basic implementation and testing complete (sans mm work)

Werner,

I have started by writing up a a comment block in m4/groff.m4 to ensure I have a logically clear explanation of the change before I start hacking code.

Does this start represent a direction that you would be happy with?

Peter

# Controllable Compatibility Mode
#
#   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, ... See the manual page groff(1)'s ENVIRONMENT section for the
#     entry on GROFF_COMMAND_PREFIX and 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 checks for a non-GNU system macros in GROFF_TMAC
#     above, which sets 'sys_tmac_prefix' to the location of any vendor
#     provided macros, then determines if any of these vendor supplied macros
#     are non-GNU implementations. A space separated list of macro names
#     requiring compatibility wrappers is stored in 'tmac_wrap'.
#
#     If 'tmac_wrap' is a non-empty list, then the make infrastructure will
#     build compatibility wrappers in the 'tmac' directory for each mentioned
#     macro name. These wrappers enable compatibility mode (.cp 1) and include
#     (.so <filepath>) the system implementation of that macro set.  The 'an'
#     wrapper gets special treatment, by including the 'andoc.tmac' macro set,
#     before loading the system implementation.
#
#     In groff version 1.22.3 and prior, if 'tmac_wrap' is a non-empty list, at
#     installation time (make install), the 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, than 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 now 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 mode, 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 proof-read 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 macro sets, the AUTOMATIC
#     installation of the vendor macro wrappers as the principal implementation
#     of a macro set for groff(1) users, may not be desirable, especially if
#     they are principally using groff(1) to format FLOSS manual pages.
#
#     The '--with-compatibility-mode=<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-mode' option are:
#       'check'  [default] Check if system has vendor implementation of macros,
#                and based on that use the 'yes' or 'no' implementation. This
#                effectively emulates prior groff releases' implementation.
#       'yes'    Install the compatibility mode 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 macro
#                implementations exists.
#       'no'     Do not install any vendor compatibility wrappers. Use the
#                groff implementation of all macro sets as the default.
#       'manual' Installed the compatibility mode wrappers as '<macro>-os.tmac'
#                in the same directory as 'yes' option ('systemtmacdir').
#                groff users can access the macro via '-m<macro>-os' option on
#                command line of a tool from the groff family. The naming of
#                the option reflects that now a manual step must be taken to
#                use the OS implementation of the macro set. This option can
#                safely be used on systems without vendor macro implementations
#                to allow for cross-platform build instructions.
#

Thanks.  I fully agree with your analysis.  It seems that for years no Solaris user ever tried to install groff, otherwise such issues would have been discovered much earlier :(

Yes, groff has evolved meanwhile, and the best solution is to change the default macros being the groff ones (for formatting with groff) but still having compatibility mode switched on, I guess.

I like your --compatibility-mode ideas, and I think it's the way to go.  However, I won't implement that for lack of time, sorry. Hopefully, others will come up with a helping hand.

Greetings,

It seems that https://savannah.gnu.org/bugs/?44708, has exposed a
portability issue in the provided groff manual pages, which has
exposed a larger issue about compatibility mode.

I needed to read the grog(1) manual page for a piece of code I'm
working on, so I typed "groff -Tascii -man .../grog.1 | less -R",
and got:

NAME
     grog -- guess options for a following groff command

SYNOPSIS
     grog -h | --help
     grog -v | --version

Which is the same as the output of Solaris' man(1) command.

Looking at grog --help, than the raw manual page source, I realised
that I was missing out on some of the desired formatted output.

After BUG-44708 mentioned compatibility mode, I search the
documentation and code and discovered that groff -man on Solaris uses
.../lib/groff/site-tmac/an.tmac (which enables compatibility mode and
loads the Operating System provided macros), and that the groff
version of the 'an' macros were installed as
.../share/groff/1.22.3/tmac/gan.tmac.  So then I tried "groff -Tascii
-mgan .../grog.1 | less -R", and got what the manual page author
intended.

NAME
       grog -- guess options for a following groff command

SYNOPSIS
       grog [-C] [--run] [--warnings] [--ligatures] [ groff-option ...] [--]
            [ filespec ...]
       grog -h | --help
       grog -v | --version

Looking at the raw source again, I discovered that the .SY/.OP/.YS
macros used by the first synopsis line where not being rendered. In
the groff manual pages, there are 34 files that use (*1) .OP (for
example), while only 9 files that define (*2) the OP macro. I then
looked at the two renderings (-man and -mgan) in a postscript viewer
for "missing content" on the grog(1) manual page and also noticed that
email addresses in the author section were missing, which the source
suggested was the rendering of the .MT macro. The stats for .MT are 33
files that use and 0 files that define. The command (*3) shows
inconsistencies in the arguments provided to the .MT macro, including
occasional quoting of '-' as in '\-' and occasional use of '\:' after
an '@' as in '@\:', I wondered if the later were from texinfo source
documentation where '@' is special. Finally I noticed that examples in
'-mgan' used a typewriter style font (Courier?), but that is was
absent from the '-man' output, seems to be related to .EX or maybe .IP
or .RS (not investigated further).

My next thought was, "That's fine, I'll disable compatibility mode",
as my particular use is predominantly for rendering Free, Libre and
Open Source Software documentation. After a little research I found
what I believe is the source of the logic in m4/groff.m4 in the
AC_DEFUN([GROFF_TMAC]) definition. Unfortunately, neither the code or
the output of 'configure --help', has enlightened me as to, how to
disable compatibility mode; short of hacking the generated configure
script and changing the paths search for system macros to something
non-existent, and even than I am not sure that would change the value
in AC_SUBST([tmac_wrap]) or AC_SUBST([g]) (from AC_DEFUN([GROFF_G])),
which all seem related to compatibility mode.

Summarizing findings to-date:

  1. groff manual pages use macros defined in the groff's 'an' or
     'an-ext' macro sets. Which IMHO is a perfectly reasonable
     approach, but which will break(*4) man(1) and groff(1) renderings
     on systems that have installed compatibility mode macro files,
     that do not contain the same macros as groff's 'an' provides.

  2. Some manual pages may have been fixed in the past to ensure they
     render correctly in compatibility mode, and now define macros
     that are present in 'an' or 'an-ext'. In-line with the DRY
     Principle (Do not Repeat Yourself), repeating the definition of
     macros can lead to a maintenance issue and unexpected results
     when these macros get out of sync.
    
  3. Macro arguments, in particular .MT, have lost consistency over time.
     This will of course happen in any project, consistency is hard in
     any project of reasonable size - even with only one author ;-)

  4. There is no way to disable compatibility mode from configure (that
     I am aware of).

As groff is the portable and de facto standard full-featured *roff
implementation these days, and most FLOSS development is done on
systems that use groff as the only *roff implementation, it seems that
compatibility mode files would likely break(*4) more project's manual
pages than having the groff macros as the default. Though systems that
don't use groff(1) for manual page rendering will still suffer when
rendering groff and other FLOSS manual pages - such systems may wish
to consider alternative FLOSS man(1) implementations (which is what
I'm going at the moment), these include man-db-2.7.1, mdocml-1.13.3
(aka mandoc) or man-1.6g, as at the time of writing. But they will
still need NO compatibility macros installed by groff as the default
macro sets.

As effectively an end user of groff, I lack the insight, history and
wisdom to offer actual solutions to the issues mentioned, but I offer
the following for the developers/maintainers consideration, note that,
some topics make multiple competing suggestions, and or pro/con
arguments to any suggested approach.

  a. Decide if groff manual pages will render with any 'an' macros, or
     only the groff 'an' macros.  Devolving to use only the lowest
     common denominator 'an' macros across the supported platform set,
     and thus allowing the reading of groff manual pages on all
     supported platform's man(1) implementations.

     Associated Thoughts:

     i)    this is portable, but very hard to maintain without some tool
           to warn developers that a macro is not portable, as the
           page will render correctly on most systems. And as seen
           earlier in the write-up, a macro that is not defined will
           render to nothing, giving the end-user no clue they are
           missing author provided content.

     ii)   this then leads to the likely inclusion of convenience macros
           in multiple manual pages, breaking the DRY principle. This
           could be avoided by generating the final manual pages to be
           installed with these convenience macros included in-line,
           from a common include file. I'm guessing soelim(1) as part
           of the build process could be a solution to this problem.

      iii) making the decision to render groff manual pages with the
           lowest common denominator 'an' macros, does not solve the
           problem for the rest of the FLOSS projects who developers
           use system's where groff is the default *roff implementation.

           It also means that groff can not use its own manual pages
           to highlight it own features or promote 'an' macro-set best
           practice. Bug Report 44708's resolution, involved reverting
           readable macro names to two letter abbreviations, this does
           not promote maintainability, let alone the semantic goals
           of projects like mdocml (mandoc).

           The conversion of groff 'an' / 'an-ext' documents to lowest
           common denominator 'an' macros would likely be non-trivial
           and is likely a poor use of developer / maintainer time.
           The developers of mdocml had a reason to write an -mdoc to
           -man converter, to promote the use of -mdoc to projects
           that need to support platforms without -mdoc macros.

  b. Make compatibility mode a configurable feature at configure time.
     Once configurable, the groff "builder" has a decision point, what
     do they wish to preference, operating system vendor macro
     compatibility or modern FLOSS projects compatibility.

     It actually does not have to be an either or choice.  Rather then
     placing the OS vendor macros in site-tmac as their original name
     (example: an.tmac), they could be installed as <macro>-os.tmac or
     <macro>-vendor.tmac, thus making their use with groff possible
     but manual via -m<macro>-os instead of -m<macro>. Making the
     possible configuration options of --compatibility-mode, one of
     'auto' (existing behavior), 'yes', 'no' or 'manual'. All options
     (except no) still need the filesystem check but groff builder, now
     has control of the decision regarding compatibility mode.

     This solves many problems in the issues raised above, and allows
     groff to be the *roff render of choice for those using FLOSS
     software, to get repeatable results on all systems (assuming that
     compatibility mode is changed to 'no' or 'manual' by most groff
     "builders"). Thus man(1) implementation that allow the choice of
     *roff implementation allow the "builder" to choose maximum FLOSS
     compatibility. This is possibly at the expense of vendor macro
     sets that exceed the groff implementation; the groff developers
     and maintainers may like to make notes in the documentation about
     known issues on given platforms.

The 'configure --compatibility-mode' option with a new manual option,
at this stage seems like a reasonable approach and should only require
autoconf / makefile changes, and could default to existing behavior
(auto), or whatever the maintainers think is the best for most users,
which IMHO might be manual. My GNU make(1) skills are reasonable to
good, but my autoconf(1) skills are negligible, so I may not be the
best candidate for implementation duties, but I think it is a
worthwhile change, so I'm willing to help.

Regards,
Peter Bray
Sydney Australia

PS: Attached is the -Tascii rendering of the groff manual pages with
-man (on a Solaris 10 system), and -mgan on the same system.

1: find .../share/man/man -type f | xargs grep -l '^.OP' | wc -l
2: find .../share/man/man -type f | xargs grep -l '^.de.*OP' | wc -l
3: find .../share/man/man -type f | xargs grep -h '^\.MT' | sort | uniq -c
*4: break in the sense that the manual page will not be rendered as the
    manual page author intended.