Re: man(7), hyphen, and minus

[Russ Allbery]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> At 2022-12-23T10:03:13-0800, Russ Allbery wrote:

>> Yeah, the difficulty lies mostly in the layering, because people can
>> write POD source that is nonsensical in a man page context but that I
>> still have to do something with.  Stuff like C<<< B<< L<foo(1)> >> >>>.

> The *roff language does not maintain a stack of typeface changes.  How
> radical a change to POD would it be to reject constructions like the
> above?

Basically impossible, alas.  It's been part of the language since the
beginning and is supported by all the other output formatters (and these
days, people arguably use the HTML output more than the man page output).

If I were designing POD again from scratch, I would do various things
differently, but at this point it is what it is.  A refrain that I'm sure
sounds familiar when maintaining groff.  :)

>> The additional problem that Pod::Man has is that I want to add double
>> quotes around literal text if and only if I'm rendering with nroff.
>> With troff, the font change is sufficient and I don't want to add
>> quotes.

> A lot of man pages use bold for literals, even on terminal devices.  I
> tend to in groff's own pages, but I _also_ quote multi-word or
> potentially ambiguous literals in case the man page is viewed in a
> context that strips the typeface (like copying and pasting into an
> email).

Yeah, Pod::Man has a whole bunch of special rules about what to quote and
what not to quote (which are now configurable as of the latest release),
mostly designed for documenting Perl.

Part of the challenge of maintaining Pod::Man is that Tom Christiansen
wrote the original intentionally to be magical: it was supposed to
understand what you were trying to do and add markup for you as much as
possible so that you didn't have to.  This was way back in the day when
that sort of thing was briefly in vogue.  Now, I think all of us have
learned that explicit is better.  :)

> Sort of.  I'd say more that it finally acknowledged the existence of ISO
> 8859 (free ECMA-94 copy here[2]).  So at long last they advise people to
> simply use ' and ", each paired with themselves.[3]

Oh, interesting.  My recollection is that GCC switched over to Unicode
quotes, so it sounds like there's some complexity here.  Or it may just be
that ' and " are the right choice if you don't already have a whole
translation layer in place so that you can downgrade Unicode quotes to
something else if you don't think you're in a Unicode environment.

>> Speaking as someone maintaining a generator, it's very difficult to
>> know when I can drop support for old Unixes.  It's also very painful to
>> be wrong; if I delete a bunch of compatibility code, and then later
>> someone really wants it back, adding it back in is awful.

> Does that mean you're not hopeful that you will be dropping support for
> Solaris troff soon after Oracle does?

I truly don't know.  I will at least seriously consider it, because
supporting it is sufficiently painful that I'd love to stop, although
discovering that groff has a variation of the same problem (\fBfoo\f(CWbar
shows "bar" in bold) means that I gain less than I would have hoped for by
removing the Solaris compatibility code.  Although that problem goes away
if I can safely use \f(CR instead of \f(CW, it looks like; I'm not sure
how portable that is, but that may be the right direction.

(The Solaris problem is that \fB\fP\f(CW\fP leaves the font set to B.  In
both cases, the problem seems to be that CW is not a "real" font.)

> I learned the following from Paul Eggert on this list just last
> month.[4]

> PE> Solaris 10 is no longer supported after January 2024, so if it and
> PE> all the other traditional troffs die out by 2024 we can stop
> PE> worrying about this then.
> PE>
> PE> Solaris 11.4, the only Oracle Solaris version that is planned to be
> PE> supported after January 2024, is based on groff 1.22.3 instead of on
> PE> traditional troff. See:
> PE>
> PE> https://docs.oracle.com/cd/E88353_01/html/E37839/troff-1.html
> PE> https://www.illumos.org/issues/12692

> This could buy you a lot of elbow room.

The thing about Pod::Man is that it's part of Perl core, so I try really
hard to be as portable as Perl is because I don't want my software to be
the thing that breaks on some obscure supported platform.  And Perl is
*really* portable (see, for instance, all the EBCDIC handling in Pod::Man)
and I have no idea if they're going to be willing to drop Solaris support
just because it's end of life.

I know Paul uses this rule for all of the software that he maintains, and
it makes a lot of sense, but I'm not in the driver's seat for this.
(Also, I'm sympathetic to the argument that Perl often is absolutely
mandatory for a system to be usable, so not being able to use the latest
Perl is more of a showstopper than, say, not being able to upgrade
coreutils.  Admittedly, bad man page rendering won't cause those problems,
but still, that's the general principle I've been using.)

-- 
Russ Allbery (eagle@eyrie.org)             <https://www.eyrie.org/~eagle/>