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

[G. Branden Robinson]

Hi Alex,

At 2024-12-20T00:39:19+0100, Alejandro Colomar wrote:
> On Wed, Dec 18, 2024 at 08:00:53PM -0600, G. Branden Robinson wrote:
> > 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.)
> 
> I prefer \[lq] and \[rq] over .QS and .QE.

If everybody just used groff (please feel free to start!), I wouldn't
bother with this proposal, for that precise reason.  My proposal is
stimulated in part by experiences contributing to the Bash and ncurses
man pages.  Both of those projects expect to be portable to a wide
variety of systems, some of which benightedly don't use groff as their
man page formatter.  Some don't even use mandoc(1), which can at least
be said to have been attentive to developments in Unix since 1995.

For some vendors, the end of the Unix Wars meant the end of development.
Lay off all the engineers and collect rents from locked-in enterprise
deployments.  Share price go up.

Anyway, there are two portability problems with \[lq] and \[rq].

1.  The \[char] syntax is a GNU troff extension.

2.  Special character identifiers, beyond what appear in the 1976
    version of CSTR #54 are not portable.  And that document specified
    no special characters for any sort of quotation mark.  Back in those
    days, you typed ` and '.  Twice if you wanted double quotes.

    So even if you spell them \(lq and \(rq, you _still_ might not get
    anything.  And, in non-groff-compatible *roffs, there's no way to
    define fallbacks for characters.  Yes, there is the ".if \w'\(lq'"
    trick, but we can't expect most man authors to think of that and we
    absolutely don't want man page sources littered with it.  (Also, I'm
    not sure there's a guarantee that an undefined special character
    has to return a width of zero.  The `\w` escape might interpolate
    some default width.  There's no standard here.)

The heroic champions of WYSIWYG/ASCII/Markdown purity have ridden to the
rescue (harassment) of harried groff package maintainers in
distributions, and prevailed upon some of them to ensure that ` and '
will never again be reliable to access quotation glyphs in man pages.

https://gitlab.com/procps-ng/procps/-/merge_requests/213/diffs?commit_id=a3ac4b667929320d4c8012435d63a9d1dd538a8d

I feel as strongly as they do that `this' is ugly in output.  But a man
source document is not output.  It's input.

I'll bet they suck at chess, too.

> BTW, that's that '*' mean?

onf answered this one.  :)

> > * 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.)
> 
> If you'd like to send some patches to the man-pages project for using
> lq and rq to replace italics, I would welcome the change.  However, I
> don't remember having seen many quotes, from the top of my head.

I wasn't thinking primarily of man-pages (the project) here.

But if I see something, I'll say something.  :)

> > * 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.
> 
> I prefer \% over a new boolean to a macro.  Both are two bytes ("\%"
> vs " 1"), and one is standard roff since forever.  Plus \% is a
> generic tool vs the boolean which a specific tool, and I tend to
> favour generic ones.

Well, the Linux man-pages likely don't have to be portable to anything
that isn't Linux, and groff is likely to always be available for Linux.

I think your preferences are sound ones.  The problem is that we have
no universally portable way anymore to ask the formatter for a quotation
mark.  If your man pages can count on an environment where that's not a
problem, by all means leave QS/QE on the shelf.

> For the same reason, I'm a defendant of cat(1) as a starter of a
> pipeline, at least when typing interactively, even if it may be
> considered a useless use of cat(1).  It actually saves typing cat(1)
> later when you find out you need sudo(8) for reading the file.

This is a good point.  I've in fact tripped over that myself.

Regards,
Branden

signature.asc
Description: PGP signature