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

[G. Branden Robinson]

Hi Doug,

Thanks for considering my proposal.  I see that I've not done the best
job documenting the problems of the status quo, and that even with that,
my solution may not suffice to address them.

At 2024-12-20T10:00:25-0500, Douglas McIlroy wrote:
> > * 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].

As noted in a follow-up of mine, I made an error here.  The `lq` and
`rq` strings came to man(7) the next year, in 4BSD in 1980.  (Day two?)

Compare:
https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/lib/tmac/tmac.an
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/lib/tmac/tmac.an.new

> >   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.)
> 
> As the guy who added .RB, .TP. etc. to v7 -man,
> I don't think of myself as one "who [wasn't] already
> practiced in *roff". As the editor of v7 volume 1, I
> wrote the man(7) page, which didn't exist in earlier
> editions.

Conceded.  You had extensive *roff experience, including as the author
of a macro package (not to mention a *roff itself), and we don't find
`lq` and `rq` strings in use in _any_ of the V7 man pages.

There's even only one false positive.

$ grep -r '[lr]q' src/unix/v7/usr/man
src/unix/v7/usr/man/man1/ar.1:.B drqtpmx,

> (The man macros had been so simple that s.tmac [sic] served as its own
> documentation.)

The pre-V7 man page macros seem to have come in three varieties.  But
yes, their macro files are short and straightforward by any measure.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=V6/usr/man/man0/kaa
https://minnie.tuhs.org/cgi-bin/utree.pl?file=V6/usr/man/man0/naa
https://minnie.tuhs.org/cgi-bin/utree.pl?file=V6/usr/man/man0/taa

(The Unix historian in me asks: why three versions?)

> The new man page documented just two strings,

Right: `R` and `S`.

(For our rapt audience, here's another link.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man7/man.7
)

> neither of which exists in groff tmac.s.

I assume you mean "an.tmac", but yes, we have them.  These two and BSD's
two as well.  Plus a `Tm` string courtesy of USG or whoever was
responsible for PWB 2.0/UNIX.

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?h=1.23.0#n1249

> If \*(lq and \*(rq were in fact defined, ignorance of them should be
> blamed on the editor's oversight, not on other authors' unfamiliarity
> with *roff.

I think part of the reason is that they were BSD/CSRG innovations, and
apparently not well socialized even there; I did some grepping yesterday
while composing a message to this thread, and uptake of \*(lq and \*(rq
was seen in less than 8% of their man page corpus (by document count),
with use of `` and '' 4-5 times higher.

> As for the issue at hand, habits and intents for the placement of
> quotes relative to adjacent punctuation are so idiosyncratic that a
> pair of macros can serve only in the simplest case.

I agree.  This is the most frustrating limitation for me.

> As if the choice among keyboard quote mark, \[lq] and \*[lq] were not
> vexing enough, the proposal adds another alternative.

You have those choices only on groff, or on groff-compatible formatters.

Our advice[1] to people enjoying a groff-compatible formatter (or
"compatible enough for man(7) work", like mandoc(1)) is as follows.

groff_man(7):

   Strings
     The following strings are defined for use in man pages.  None of
     these is necessary in a contemporary man page; see
     groff_man_style(7).
...
     \*(lq
     \*(rq   interpolate special character escape sequences for left and
             right double‐quotation marks, \(lq and \(rq, respectively.

groff_man_style(7):

   Font style macros
     Use italics for emphasis rarely, and bold almost never.  Brief
     specimens of literal text, such as article titles, mentions of
     individual characters or short strings, and (sub)section headings
     in man pages, are suitable objects for quotation; see the \(lq,
     \(rq, \(oq, and \(cq escape sequences in subsection “Portability”
     below.

...

   Portability
     \(lq
     \(rq   Left and right double quotation marks.  Use these for paired
            directional double quotes, “like this”.

     \(oq
     \(cq   Opening (left) and closing (right) single quotation marks.
            Use these for paired directional single quotes, ‘like this’.

Why do we need to say this?  Because the Philistines rose in revolt when
they got UTF-8 terminal emulators, and campaigned to take ` and ' away
from us.  So these characters _no longer reliably produce quotation
marks_.  I've linked before to my screed on the subject.[2]

That is a significant development since 1979.  In this respect, life is
now harder than it was then, and something must be done to restore the
lost functionality.  Unfortunately, the foregoing special character
escape sequences are not universally portable.

> It may rope in \c as well.

I concede that I am unhappy to create a new site for `\c` usage.  We
can't kill it, but I don't feel good about proliferating it.

> So I question its justifiability.

I appreciate your giving my proposal red-team scrutiny.

> The longer the -man man page gets, the less it will be heeded.

I have to grumpily observe that the heedless equines are mere dots on
the horizon from the vantage point of the groff_man(7) barn doors.

Despite having given public presentations on the value and practices of
man page composition as far back as 2005, I spent little time reading
that man page myself until I joined groff development.  I believe James
Clark (or whoever contributed the page) made a painful error in leading
its presentation with the "Options" section, as if the primary users of
the document would be people typing a groff or nroff command by hand who
were also desirous of fine-tuning formatting parameters.

Contrast:

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/groff_man.man?h=1.22.3

with:

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/groff_man.7.man?h=1.22.4

I thought that was poor prioritization, and decided that the primary
audience for the man(7) macro language was people who needed to compose
documents using it.

Almost no one has communicated with me to tell me I made the page better
_or_ worse.

It is assuredly longer than your V7 page, linked above, and the
fleshed-out "HOWTO"-esque groff_man_style(7) twice as long yet.

Spiny cactus that I am, I have appreciated a drop or two of
acknowledgement.

        "I started by using pandoc to reformat Markdown as a man page.
        Then I converted the docs to asciidoc and used `asciidoctor` (or
        `asciidoc`) to convert that to a man page.  Finally, I spent
        about ~4-6 hours learning the basics of `roff` and how to write
        a man page.  It would have taken me a lot less time had I know
        about the existence of `man groff_man_style`.  On a Linux system
        at least, _that's_ where the gold is."[3]

> That said, I do prefer macro calls to backslash escapes embedded in
> text. I just think that the present proposal is insufficient to the
> task. And \c is the nail in the coffin.

Hmm.  Well, if we're not going to have a pair of universally portable
macros to recover access to the quotation marks taken from us by the
howling asylum inmates that beset the largest GNU/Linux distributions,
what can be done to obtain quotation?

Anyone running groff(1), mandoc(1), or a formatter providing relevant
groff extensions (like Heirloom Doctools troff) can avail themselves of
the four special character escape sequences noted above.

But what about those who don't run such modern software?  What of modern
projects that desire portability to legacy systems?

They can do what ncurses does.

.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.\}
.el \{\
.ie t .ds `` ``
.el   .ds `` ""
.ie t .ds '' ''
.el   .ds '' ""
.\}

https://github.com/ThomasDickey/ncurses-snapshots/blob/86378f5b4b9c8a32f279e1c9f473350590d26b10/man/ncurses.3x#L33

...and use these \*(`` and \*('' strings for double quotation.

Analogues for single quotation are left as an exercise for the reader.

People may also want to recover from the _other_ damage imposed by the
Bro Brigade's mission to make man(7) documents look more like Markdown.

.ie \n(.g \{\
.ds ' \(aq
.ds " \(dq
.ds ^ \(ha
.ds ~ \(ti
.\}
.el \{\
.ds ' '
.\" \*" is not usable in macro arguments on AT&T troff (DWB, Solaris 10)
.ds " ""\" two adjacent quotes and no space before this comment
.ds ^ ^
.ds ~ ~
.\}

https://git.savannah.gnu.org/cgit/bash.git/tree/doc/bash.1?h=bash-5.3-testing&id=f223b24c4b299f00b64e68ca7f066e5bb4f717a0#n22

If we're not doing to have some macros to address the problem of
portable quotation problem, where should advice along the foregoing
lines be maintained?  As another Q&A at the tail end of
groff_man_style(7)?  Somewhere else?

Always a pleasure to hear from you, Doug.

Regards,
Branden

[1] hammered out by Ingo Schwarze and me several years ago
[2] 
https://gitlab.com/procps-ng/procps/-/merge_requests/213/diffs?commit_id=a3ac4b667929320d4c8012435d63a9d1dd538a8d
[3] 
https://www.reddit.com/r/rust/comments/184ijwg/ripgrep_14_released_hyperlink_support_regex/

signature.asc
Description: PGP signature