Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '.

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sat, Oct 31, 2020 at 02:41:32PM +1100:

> No release has been made and several courses of action are possible.
> 
> 1. Advise distributors and direct consumers of groff releases to apply
>    the remappings in their site man.local (and mdoc.local[2]) files)
>    if they don't want to see the buggy man pages and (presumably)
>    participate in an effort to get them fixed.
> 2. Restore the remappings, but in our tmac/man.local.  Distributors and
>    direct consumers will have to perform a merge with their existing
>    files.

Please take man.local out of the equation.  Such a thing simply
doesn't exist on FreeBSD, OpenBSD, NetBSD, or Dragonfly, and it
won't be created on OpenBSD.  If the change isn't reverted in groff
upstream, we may have to patch groff/tmac/an-old.tmac outright in
the groff port to restore acceptable behaviour.

> 3. Restore the remappings to tmac/an-old.tmac, but make them
>    conditional on a register that defaults off.
> 4. Restore the remappings to tmac/an-old.tmac, but make them
>    conditional on a register that defaults on.

OS-local changes solve little in the first place.  Manual pages are
supposed to be as operating-system independent as possible, such
that pages from one system can also be read on another, and such
that authors of portable software know what to do.  You seem to be
advocating ecosystem fragmentation, making manual pages non-portable,
which astonishes me.

I have no preference among options 1 to 4.
They are all equally bad.

> 5. Revert the change[3] entirely.

That seems to be the only reasonable course of action to me.
And not just for now, but for good.

> 6. Revert the change an un-fix the misuses of ` and ' in code
>    specimens that I've been repairing for the past few years.

That is not needed.  There is nothing wrong with the few people who
know and want to  using the escape sequences that are required for
general-purpose roff typesetting even in manual pages.


By the way, the problem is not only changing thousands of existing
manual pages - which can't be automated; every single instance of '
and ` would have to be checked manually.  Here is a list of *a few
examples* of affected manual pages from OpenBSD base alone.  The
list is definitely far from comprehensive, these are just some
examples:

  section 1: bc, csplit, expr, find, flex, getopt, grep, ksh, ldap,
    less, mandoc, more, paste, pax, shar, ssh, su, tar, tmux, vi,
    xargs

  section 3: BIO_f_ssl, EVP_PKEY_keygen, RMD160Init, SHA256Init,
    SSL_CTX_set_alpn_select_cb, SSL_CTX_set_default_passwd_cb,
    cgetent, fgetln, fgets, getopt, getopt_long, malloc, stpcpy,
    strchr, strcspn, strncat, strncpy, strrchr, strsep, strtol,
    strtoul, va_start, wcslcpy, wcsrchr, wprintf

  section 5: ifstated.conf, nsd.conf, pf.conf, pf.os, relayd.conf

  section 7: ascii, ports, roff

The problem is that manual pages are written by software developers,
not by typesetters, who are used to typing programming languages
and who are used to the fact, from the past, that these five
characters do not need escaping.  So new problems will continuously
creep in.  Theoretically, i might be possible to educate *BSD base
system developers, which are maybe a thousand people all told,
alienating part of them, as Anthony explained.  I explained in my
first mail why this massive education effort is not worthwhile
because it provides little benefit: the current rules are simpler
than the proposed ones and they are adequate for the particular
needs of software documentation.  For GNU/Linux and for portable
software, i see no chance for such an education project even if it
were desired.

Yours,
  Ingo