Re: custom NS and NE man(7) macros

[G. Branden Robinson]

Hi Doug,

You didn't say, but I reckon this is a survey of man(7) macros that
might be considered extensions?

At 2023-09-25T19:26:13-0400, Douglas McIlroy wrote:
> Used in connection with man(7):
>         PS/PE

That one's pretty rare.  It may be that most page authors are too lazy
to write fallback or alternative content for nroff devices.

I see

          EQ/EN

more often than pic(1) usage in practice.

>         TS/TE

Frightfully common.  And useful in the absence of dedicated display
macros.

> Used in other popular macro packages:
>         KS/KE

Yes.  ms(7) has these keep macros and I want them really badly for
man(7).

>         DS/DE

Also from ms(7); already discussed at some length in this thread.

>         RS/RE

Another ms(7) feature; present in man(7) since day one, so not an
extension.

> In hindsight I plead guilty to
>         EX/EE

I don't think you need to feel any guilt here.  People violently desire
to switch to a monospaced face when typesetting examples.  I've spent a
lot of time recently writing explanations of why this is damned hard to
do portably.[1]  It's good to have macros to conceal the hoops one must
leap through to obtain such a typeface.

> Questionable newcomer in man(7)
>         UR/UE

Hyperlinks are a revolutionary development, with inherent support in 3
of groff's most important output drivers: grohtml(1), gropdf(1), and
grotty(1).

> And now, run up the flagpole for man(7):
>         QO/QC
> What's the rationale?

As with the difficulty of selecting a monospaced typeface, it's damned
hard to portably obtain attractive quotation marks.[2]  The consequence
is that many man(7) authors despair and don't bother with quotation at
all.  That is a pretty deep defect in professional-grade technical
writing.  (Abuse of italics is one common compensatory approach.)

The idea here is that maybe people will employ quotation if it is very
easy to do so.

Regards,
Branden

[1] For example:
    https://github.com/Perl/perl5/issues/21239#issuecomment-1645998105

[2] "Define more attractive and useful strings for rendering double
    quotes.  If the formatter claims groff compatibility (sets the `.g`
    register), define the `` and '' strings to the `lq` and `rq` special
    characters, respectively.

    Otherwise, if a typesetter is being used (the `t` condition is
    true), use the existing fallback of "``" and "''" character
    sequences, which troff implementations map to (repeated) directional
    single quotes.

    Otherwise, a non-groff-compatible nroff is in use: define both
    strings to interpolate ", a.k.a. U+0022, a non-directional double
    quote.  Doing this requires knowledge of a detail of the `ds` *roff
    request: a leading double quote is removed, permitting a string's
    contents to begin with leading spaces (or tabs).  Thereafter, double
    quotes are treated literally."

    https://lists.gnu.org/archive/html/bug-ncurses/2023-09/msg00074.html

signature.asc
Description: PGP signature