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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Wed, Oct 21, 2020 at 02:44:44AM -0400:

> commit 697e6db7fcacd403f5dde682002d02caa52e48df
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> AuthorDate: Mon Oct 19 04:40:31 2020 +1100
> 
>     tmac/an-old.tmac: Stop remapping ` and '.
>     
>     Our own pages now appear to be clear of wrong-quote problems, so let's
>     make them visible if they recur.  Those who don't want to fix bad man
>     pages (distributors, site admins) can restore the mappings in their
>     man.local files.

I think this commit ought to be reverted.  Sorry for not finding the
time earlier to inspect its consequences and to discuss it with
fellow documentation maintainers.

To start explaining why i consider this change bad, i should like
to quote Anthony J. Bentley, with his permission:

:: As a rule I correctly escape ` as \` and ' as \(aq even in manpages.
:: They're actually needed less often than one might think. But most
:: developers (even many manpage authors!) are unfamiliar with this
:: historical oddity in troff. Expecting them to remember this rule
:: and get it right is too much. Searching the corpus of manuals to
:: correct all missing escapes is also too much.
::
:: In the proposed fantasy world, everyone would be intimately familiar
:: with the rules of elegant typography. Groff could make its change,
:: and no manpages would suffer.
::
:: In the current world, ` and ' and such are always displayed literally.
:: It means I give up my curly quotes in favor of a slight typographical
:: downgrade, but important content (command/config examples, source
:: code, etc) is never wrongly transformed. This is what we have in
:: the www repository, and with the current mandoc rendering, basically
:: what we have in base also.
::
:: Groff making its change will take us to a third place, where because
:: manpages are often poorly written and the distinction between escapes
:: is subtle and poorly understood, manpages will often be poorly
:: rendered and correcting the changes will be a lot of unpopular,
:: frustrating busywork.
::
:: As an example, I point you to this commit, where I fixed multiple
:: pages whose authors decided to turn apostrophes into *acute accents*
:: and never noticed. It's worse than bad kerning!
:: https://marc.info/?l=openbsd-cvs&m=155945840114941&w=2
::
:: I'm sympathetic to groff here. I can see why they want to fix a
:: rather glaring divergence between terminal and PDF output. But in
:: my opinion the change will cause more rendering problems than it
:: will fix. The minor typographic gain of pretty quotes in prose will
:: be offset by the far worse typographic loss of unescaped literal
:: ASCII ' and ` in command contexts, most of which will never be
:: fixed.

Let me add that the current rules for manual pages are not wrong,
they are merely slightly *different* from the rules for general-
purpose roff typography.

For general typography, we have:

  input  output
  `      U+2018 left single quotation mark
  '      U+2019 right single quotation mark
  \(ga   U+0060 grave accent
  \(aq   U+0027 apostrophe-quote

That does make sense for general typography, in particular for
texts that are not concerned with computer programming, because
quotes appear frequently in such texts, a grave accent without
a supporting character is very rarely needed, and the ASCII
apostrophe-quote is almost never needed; it isn't even a real
character in general-purpose typography.

In contrast, the current rules for manual pages are:

  input  output
  `      U+0060 backtick for shell command substitution and the like
  '      U+0027 programming-language single quote
  \(oq   U+2018 left single quotation mark for running text
  \(cq   U+2019 right single quotation mark for running text

Even if we were to design all this from scratch - which we cannot
do since many thousands of manual pages already exist -, that would
be a better design for manual pages, for three reasons:

 1. Literal ' and ` are frequently needed in manual pages,
    programmers will constantly forget escaping them, and when
    they are escaped, they make the manual page source code
    very ugly, hard to write, hard to read, and error-prone.
 2. Typographical quality of single quotes is not nearly as
    important in manual pages as in technical texts, so even if
    escaping them as \(oq and \(cq is forgotten, it doesn't
    really matter.
 3. Manual page authors rarely need to type \(oq and \(cq by hand
    in the first place but will normally use macros like .Sq
    or .Ql which do that automatically, so there is no burden
    on manual page authors.

The strongest reason why this should be reverted is that it is an
incompatible change both ways with little to no hope of ever fixing
the consequences.  Correctly written old manual pages using ` and '
literally e.g. in code samples will suddenly render incorrectly
with new formatters, in an important way.  Correctly written new
manual pages that no longer escape \(oq and \(cq and instead rely
on the general typesetting rules will look worse with old formatters.
As explained above with the points 1-3, these downsides will not
even be offset by any advantages, but will in addition make life
harder for manual pages authors for no benefit.

Arguably, there is a very minor benefit of the change.  People who
write both manual pages and use roff for general-purpose typography
have to learn fewer rules.  But such people exist in much smaller
numbers than people merely writing manual pages.  They have to
learn a lot more than people merely writing manual pages anyway,
so the additional rule is no burden for them.  And finally, even
those people don't need to remember any differing rules if they
simply use \(aq, \(ga, \(oq, and \(cq only in manual pages if they
want to.

Finally, the change as committed is incomplete.  It changes the
rules for the man(7) macros but leaves the identical rules for the
mdoc(7) macros unchanged.  I think trying to explain to manual page
maintainers that quoting rules in manual pages depend on which macro
set is in use would be an extremely bad idea, it would be utterly
confusing.  That alone - the change being inconsistent and incomplete -
would already seem sufficient to me for requesting a revert, even
if it wouldn't be a bad change for all the reasons explained above.

Your argument that distributors and packages of groff can individually
decide to revert your change if they want to is an even worse idea.
That would result in ecosystem fragmentation.  You want different
rules for manual page markup depending on the operating system?
You want that the manual pages from one operating system render
incorrectly on another system, and vice versa?  What about the
manual pages of portable software - those poor people would be
*forced* to escape everything: \(aq, \(ga, \(oq, and \(cq - not
as a choice because they want to, but to get correct rendering
on all systems.  Inviting distributors and packagers to mess with
these rules clearly exacerbates the problems rather than helping to
solve them.

If groff insists on this change, then mandoc and all systems using
it (OpenBSD, FreeBSD, NetBSD, Illumos, Alpine Linux, Void Linux)
will probably be forced to follow your advice to not follow groff
and to patch your change out of groff.  I don't see what the
alternative would be...  And i'm not sure what Fedora could do,
which officially supports both man-db/groff (by default) and mandoc
(which can be activated with its "alternatives" configuration system).

Yours,
  Ingo