Re: hyperlink for doc.tmac (man:, mailto:)?

[G. Branden Robinson]

Hi Mingye,

At 2023-04-08T13:46:37+0800, Mingye Wang wrote:
> Groff 1.23 introduced .MR in an.tmac with hyperlinking, so out of
> curiosity I checked doc.tmac for anything analogous. It looks like the
> .Xr macro there is a little bare without any reference to a "man:" URI
> scheme; so are the .Mt and the .Lk macros.
> 
> It doesn't seem to emit any links, in fact: there's nothing analogous
> to the fancy "an*hyperlink" bits in doc.tmac as far as I can tell.
> Indeed,`groff -mdoc -Thtml <(zcat /usr/share/man/man7/groff_mdoc.7.gz)
> > gm.html` (with groff 1.22.4) gives the expected italicized but not
> linked text.

These observations are all correct.

> Is adding hyperlink support for -mdoc anywhere on the roadmap?

Officially, no.  Unofficially, yes--it's something I'd like to work on
after 1.23.0 finalizes and is truly released.  A few months ago I
started revising the groff_mdoc(7) man page and changed a few minor
aspects of the package's behavior.  (I changed some font assignments,
which in groff are user-overridable in the mdoc.local file, and I
changed the way .Sx marks its arguments--they now use quotation rather
than a typeface change.)

One of the things I was pleased to be able to get into groff mdoc(7) for
1.23 was PDF bookmark support (commits a11a0772e6 and 98112bfeca).

As I work my way through the man page revision I expect to find other
things I want to alter, or at least complain about; I feel that mdoc
advocates have gone unrebutted in their claims of superiority over the
man(7) package for much too long, and since no one has stepped up to
write that rebuttal I guess I'll have to.  The choice of mdoc vs. man,
like man pages vs. Texinfo document or vi vs. emacs, is a matter of
weighing tradeoffs and making a decision, not a matter of one technology
being superior in every way to its alternative, and all those who fail
to adopt the "better" choice being morons.  Much mdoc(7) advocacy seems
to find itself straining to resist stating the latter outright.

So while I am happy to work on groff's mdoc implementation, I'm not
going to join a conspiracy of silence about the package's flaws.

Also, on a purely engineering level I want to see what kinds of problems
crop up with groff man(7)'s `MR` and other link support (since I expect
OSC 8 support to draw more attention to `UR` and `MT`).

I can think of two issues that annoy me:

1. https://savannah.gnu.org/bugs/?63470
2. A long URL that is formatted as text (e.g., when hyperlinks are _not_
   available) can cause adjustment warnings.  On typesetting devices,
   I've considered applying track kerning to them.[1]  But that's no
   help for terminals.  I'll have to come up with some kind of
   workaround, and I'm afraid it will require some ugly stunt.  The
   cleanest but most intrusive solution I can think of is to eat some of
   our remaining escape sequence name space to have a new escape
   sequence that means "don't warn if this line can't be adjusted".  But
   I have about that being a good solution, too.  (People who never want
   to see man page text adjusted will never have to cope with this.)

Anyway, the reason for waiting until the man(7) hyperlink issues are
sorted out is that I then have something clean and well-tested I can
"port" over mdoc(7).  Our mdoc(7) support doesn't get nearly as much
exercise as man(7), in part because so many readers of mdoc(7) pages
have embraced mandoc(1).

Regards,
Branden

[1] https://savannah.gnu.org/bugs/index.php?62060

signature.asc
Description: PGP signature