man(7), hyphen, and minus (was: [tz] Doubts about a typo fix)

[G. Branden Robinson]

Hi Russ,

[finally getting back to this]

At 2022-11-28T08:45:34-0800, Russ Allbery wrote:
> "G. Branden Robinson via tz" <tz@iana.org> writes:
> 
> > Most people won't see a difference because groff 1.22.4 (and earlier
> > releases going back to, I think, 2009) the man(7) macro package
> > remaps the hyphen to the minus sign on the 'utf8' output device.
> > This will be changing in groff 1.23 to improve consistency with man
> > page rendering on typesetters.[1]  Workarounds are documented.[2]
> 
> Debian may have to override this locally again.

Yup.  I've already discussed this likelihood with Colin Watson.[1]  It
doesn't upset me; the right site for decisions like this is the
distributor's man.local and mdoc.local.  By confounding the glyph
distinctions in the macro package itself, we erect a barrier to the
problems ever being corrected.  So I'mma make like Gorbachev and tear
down that wall.

> I remember the days before 2009 when this was the case, and it caused
> no end of problems, usually with cutting and pasting switches or code
> examples.  Sadly, a large number of upstream man pages used -
> incorrectly.  (Even putting aside the problem that, technically, you
> need \N'45' or some similar thing because \- is supposed to be minus
> rather than the ASCII hyphen, as noted in your second link.)

Right.  Four or five years ago I proposed a new groff special character
identifier `\(hm` to cover this case.  But this was not met with assent,
and I concede that the problem may be confined to man pages.

In any other *roff document, a page that really wants \N'45' and has
confidence that the font that's going to render it is ASCII-encoded (or
compatible at this code point), can define a string or character to
obtain it.

I also see the wisdom in Werner Lemberg's decision years ago to close
groff's predefined special character identifier name space to any
expansion without damn good reason.  Of all proposals I've seen, \(hm
has the strongest case--if that can't make it over the hurdle, it seems
unlikely that anything else will.

> We tried clean up all the problems previously, but it was like bailing
> out the ocean, and I think we stopped once groff changed its default
> mapping.

Right.  I regret that groff changed so as to make the waters
indistinguishable from the fish.  Now people who want to go fishing will
have a way to render the waters transparent again.

(I think I did some violence to your metaphor there.)

> > mandoc maintainer Ingo Schwarze and I both recommend against
> > performing string definitions, or interpolating strings, in man
> > pages.
> 
> Pod::Man of course does tons of this.  I'm always open to
> alternatives, but they're all there for a reason....

Oh, I know.  I've seen Pod::Man's preamble.  I think what distressed me
originally about it was that, like docbook-to-man, it seemed to make
man(7) seem like a write-only language.

In the years since, I've come to appreciate and respect the quality of
Pod::Man's _output as rendered_, which cannot be fairly equated to
docbook-to-man's.

I also have reason to believe that the people behind Pod::Man were and
are deadly serious about implementation quality, and sadly I fear little
evidence of the same can be mustered regarding docbook-to-man.

Maybe after 1.23.0 is finalized I'll make some time to look again at
Pod::Man, and if I see any easy wins I will certainly recommend them to
you.

The EOLing of Solaris troff is fat with the promise of opportunity.
It's my hope that Illumos won't need much of a nudge to jump to groff,
Heirloom Doctools, or neatroff, any of which would be an improvement
because they're _maintained_.

(Well, Heirloom has slowed _way_ down...[2])

Regards,
Branden

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1011666#25
[2] https://github.com/n-t-roff/heirloom-doctools/commits/master [3]
[3] I checked, and we can draw a spline with 100 points with no problem.

signature.asc
Description: PGP signature