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

[Anthony J. Bentley]

Hi Branden,

On Thu, Oct 29, 2020 at 5:06 AM G. Branden Robinson
<g.branden.robinson@gmail.com> wrote:
> The escaped versions of these characters are actually needed less often
> than one might think.  That is a quantitative observation of significant
> qualitative impact.

I agree. If it were merely a matter of paying attention while
authoring new manuals, it wouldn't be a serious problem. But...

> The apostrophe is admittedly more frequent.  But not ultra-common.

Literal ASCII apostrophe is incredibly common in existing manuals,
whether shell examples or configuration files or source code snippets.
As is ~. If ` and ' get transformed to quotes in terminal output,
transforming ^ and ~ to U+02C6 and U+02DC can't be far behind.

> > :: Searching the corpus of manuals to
> > :: correct all missing escapes is also too much.
>
> Yes, but no one has proposed a mission for doing so; there's no deadline
> and no flag day.

Changing the rendering without fixing manuals is not free. There is a
cost in user frustration. You argue that manpage authors should be
aware of troff's idiosyncracies, but surely you don't think *readers*
have the same obligation. (Well, reading further into the mail,
perhaps you do!)

I fear a loss of mindshare. These days documentation is often an
afterthought. Quality man pages even more so. I've spent considerable
time and effort convincing authors to consider a typesetter they
consider to be archaic. I think it likely that triggering unexpected,
frustrating rendering changes like this will drive software developers
even further in the direction of HTML and Markdown.

> As you've pointed out in the frequency studies I did a
> few years ago, raw counts get thrown off by the high volume of man pages
> that are actually composed in something else altogether, like DocBook or
> POD.  Fix those tools, and many pages correct these defects as soon as
> they are generated again.

In OpenBSD alone, uses of ', `, ~ and ^ that will need escaping number
easily in the thousands—and I'm only including uses within
human-authored -mdoc pages in that number.

I don't share your optimism that roff-generating tools will be fixed.
DocBook's generated manpages have been truly awful for many years;
when has that ever improved? Does POD even provide a capability to
semantically separate prose from code literals and escape characters
accordingly?

Similarly, I don't share your optimism that manuals themselves will be
fixed, slowly or quickly. Especially since you suggest distributions
turn this off in man.local or render manuals in ASCII!

> It may thus perhaps be a mortifying realization on your part that I have
> plans to fix all our hyphens, too, and remove _that_ part of our
> an-old.tmac, too.

I'm not familiar with this. Are proposing translating - to U+2010 as
well? Will you argue that literal ASCII hyphens are "not ultra-common"
in manpages too? Be serious.

> The ASCII committee actively promoted ambiguity.  Later, Knuth and the
> *roff progenitors used that ambiguity as foundation stones.  AT&T troff
> _never_, before Plan 9 anyway, grew special character escapes for _any_
> type of quotation mark.  [adoclr]q?  All groffisms.
>
> What was Murray Hill's solution to the problem of confusable glyphs?
>
> They trusted the user to figure it out.

They trusted the user, in an environment where a higher proportion of
readers were familiar with the formatting language in question, where
there were few alternative means of producing documentation, and
perhaps most importantly, where copy & paste did not exist.

This change visibly and obviously affects tens of thousands of troff
documents in the output format in which they are most often read.
Whatever groff does in the end, I just feel like something with such
an impact deserves some discussion first.

-- 
Anthony J. Bentley