[bug #44784] groff-git_2015-04-04: Compatibility Mode rendering of groff manual pages

[anonymous]

Follow-up Comment #4, bug #44784 (project groff):

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.
#


    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?44784>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/