Re: Proposed: QS/QE macros for quotation in man(7)

[G. Branden Robinson]

Hi Dave & Alex,

I started out off-topic and then wandered back onto it.  To remedy
that, I've moved the on-topic part to the top of this message.  Replies
to your messages follow below.

There seems to be no objection to the core proposal (so far).  Nobody
addressed the initial-word-hyphenation-suppression-argument issue.  So
let me re-propose the macros thus enhanced.

Synopsis:

.QS [suppress-initial-word-hyphenation?]
       Begin quotation.  An opening quotation mark is formatted.  The
       line is not broken.  The optional argument is a Boolean value
       (“0” or “1”) indicating whether automatic hyphenation of the
       initial word should be suppressed.  The default is “0”.

.QE
       End quotation.  A closing quotation mark is formatted.  The line
       is not broken.

Pro:
* People may discover that quotation marks are properly available in
  the man(7) language, a fact that has been obscure for 45 years.  (The
  `\*(lq` and `\*(rq` syntax has been available since day one [1979].  I
  suspect these failed because man page authors who weren't already
  practiced in *roff had no idea what a *roff string was, or how to
  interpolate one, and the elaborate syntax filled them with fear.)

* A consequence of the above is that bold and italics may be abused
  for quotation purposes less, and since quotation marks will survive
  copy-and-paste operations, those operations will become more reliable
  for users.  (This might slightly increase pressure on man page authors
  to ensure their examples are correct.  Horrors.)

* People are going to reasonably want to suppress hyphenation sometimes
  in the first word in a quotation, because it will often be a
  programming language literal or similar.  Chet Ramey (Bash maintainer)
  uncovered this requirement in less than a month, as I recall.

Con:
* man(7) macros generally don't take Boolean flag arguments.  mm(7) uses
  them to arguable excess.  I'm not thrilled to introduce one to man(7).
  But it seems better than alternatives like having TWO "start
  quotation" macros, or telling man page authors to manipulate
  registers, which we otherwise stridently advise them not to do.

* mandoc(1) is likely to format the Boolean flag argument as text and
  otherwise ignore the macro.  Even if Ingo puts in QS/QE support on the
  same day I do, there will likely be a skew period for mandoc(1)
  users.

  Mitigating this is that in many contexts, a stray "0" or "1" will be
  recognized as garbage and disregarded by the reader.  With a little
  luck, in many situations the extraneous text will be harmless to
  comprehension.

  A further potential mitigation is that Ingo could decide to reverse
  his (or Kristaps's?) decision to un-roffishly format all arguments to
  unrecognized macro calls as text.  He could ignore them instead, as
  *roffs do.  This might not be a disruptive change, as mandoc(1), at
  least in CVS, has come to support all or nearly all groff man(7)
  extensions anyway.

Not a problem I'm trying to solve:
* Suppressing hyphenation in the entire quotation.  We have available
  already a leading `\%` for every non-initial word.  If you want
  hyphenation off for a giant swathe of text such that you will complain
  of having to type a word-initial `\%` over and over again, consider
  whether you in fact have a run of literals so lengthy that it should
  be displayed rather than inline.  This is what `EX` and `EE` are for.

Nobody has as yet commented on the custom quotation mark feature that I
said I was leaning against.  Unless it suddenly catches fire among the
masses, I see no reason to implement it.  Should it ever experience
demand, it can be added later without breaking the interface.

The nested-quote-style-alternation feature can be grafted on later as an
internal extension, meaning no interface change will be necessary.  I
don't expect many users to nest quotations in any event.

At 2024-12-18T14:48:35-0600, Dave Kemper wrote:
> On Mon, Dec 16, 2024 at 8:28 AM G. Branden Robinson
> <g.branden.robinson@gmail.com> wrote:
> > I don't feel I have sufficiently broad knowledge of what man-parsing
> > tools are out there besides *roffs and mandoc(1).
> 
> Fair enough, and perhaps a decent reason on its own to be conservative
> with language additions.
> 
> > Plan 9 troff is out there, retains the old AT&T/DWB troff limitation
> > of two-character names, and in fact implemented the newest groff
> > man(7) macro, `MR`, before we did.[2]
[...]
> > That said, I have suspicions that Plan 9 from User Space users don't
> > use its troff to render non-Plan-9 man pages.
> 
> Having used numerous flavors of Unix over the years, I find it hard to
> conceive of an OS package that's so complete that no users ever
> download supplementary software.  And once you introduce off-brand
> software packages, you're soon introducing off-brand man pages.  So
> Plan 9 troff might predominantly, but not exclusively, render Plan 9
> man pages. This, to me, also argues for keeping new -man macro names
> to two characters.  (And also makes me wonder what sort of bunker the
> Plan 9 troff developers are living in that they haven't heard of the
> latest 1990s innovations in software design.)

I've more than once set up a little Plan 9 or Inferno VM for myself to
play around in, since everything is supposedly so much more Unixy and
better.

I never stay long.  I've failed to productively introspect why.

> On Mon, Dec 16, 2024 at 4:19 AM Alejandro Colomar <alx@kernel.org>
> wrote:
> > I think for consistency sticking to the short format is a good
> > thing,
> 
> Both of you made this point, which I find much less convincing than
> the above points.  Don't get me wrong, I'm a fan of consistency--but
> when it aids comprehension, not simply for consistency's sake.  Using
> a consistent name for a widget, or using conventional English
> spellings and punctuation, create fewer barriers to understanding.
> Maintaining this long-obsolete macro-naming practice creates more
> barriers to understanding (albeit only the latest barriers in a
> language already replete with them).

I guess I'm saying something pretty close to that.  I see the marginal
increase in incomprehensibility imposed by `QS` and `QE` to be pretty
small compared to the known-positive-but-unknown-precise-magnitude of
marginal grief to be added in parsing compatibility and thus portability
that `QUOTE-START` and `QUOTE-END` would bring.

> As one of you wrote in the unrelated "Novel use of .char" thread: "We
> still build monuments to Ken Thompson when deciding how to name
> things.  Every concept affords a one-letter abbreviation, two at most,
> and any ambiguity that arises is purely a figment of the reader's
> sadly limited intellect."  (My only quibble with this is that I
> wouldn't lay it entirely at Ken Thompson's feet.  If giving every
> variable a MeaningfulCamelCaseName means you run up against storage
> limitations significantly sooner, you learn to be terse.)

I agree.  And when I publicly roast Ken Thompson for the many sins of
his thoughtless self-appointed disciples, it is mainly out of a sense of
fun.  And iconoclasm, of course.

I think you're right.  We too easily forget the constraints the Murray
Hill Unix Room people were working under.  Memory was scarce.  I/O was
slow.  Even the user interface hardware, a five hundred pound floor-
standing typewriter, was huge, hot, noisy, and--compared to today's
keyboards--as exhausting as a manual push lawn mower to operate.

The process of writing good code has been studied extensively, and while
it remains a combination of craft, science, and art, with much room for
personal expression, it very poorly resembles opening a copy of the
Lions book and aping it as slavishly as you can, no matter what you're
writing.

But we got at least an entire generation of that crap.

> One final point unrelated to the macro names:
> 
> > B2. It would be trivial to support the British, who use the wrong
> >     quotation marks^W^W^W^W^Wdrive on the wrong side of the
> >     road^W^W^W^W^W^W^W^Whave a different quotation mark convention.
> 
> One argument against this is that the difference between American and
> British quoting conventions goes beyond which quotation marks are
> used; it also affects on which side of a closing quotation mark a
> period or comma goes.  And there's no way for groff to figure that
> out, which means that, if the macros implement this propoasal, they'd
> be modifying only one aspect of quoting style--which might make the
> other one seem even more out of place (at least to those sticklers who
> notice such things).

At 2024-12-18T22:08:53+0100, Alejandro Colomar wrote:
> Hmmm, good reminder.  The British are right on the quotes.  Just like
> their wall plugs are the best.  A couple of things the British did
> well.

I agree that the British have the better punctuation placement
convention.  And yes, their consumer grade electrical interface is a
marvel.

I'm also interested to read this:

https://www.christianwolmar.co.uk/book/british-rail/

...and last, but not least, they pronounce "status" more correctly than
American English speakers (like me) are trained to.

But now that I've conceded three things, I must pivot back.  "PROE-cess"
and "PROE-gress" are gauche.  The Canadians, eternally trembling with
fear of being mistaken for Yankees, seized these habits too.  The
post-American Revolution RP vowel shift is nonsense, an affectation of
the posh, the very sort of people that the Monty Python troupe rightly
mocked as twits.

Not that Cockney (or its descendants) are any better.  Worse, probably.
Joe Strummer sounds like he should have gone up for the role of Simple
Jack in _Tropic Thunder_.  To hear good English in the U.K. I suspect
you've simply got to get away from London.  I was in Northern Ireland
briefly (before Brexit).  People were quite pleasantly intelligible
there.  Just as much as across the invisible, un-checkpointed national
border, one of the most civilized things I've ever seen.  Of course it
had to come under threat.  :(

Regards,
Branden

signature.asc
Description: PGP signature