Re: We have OSC 8 terminal hyperlink support now

[G. Branden Robinson]

Hi, Alex!

At 2021-10-02T18:45:58+0200, Alejandro Colomar (man-pages) wrote:
> I was curious why man: and not man://, so I had a look at what uri(7)
> says about it.  Curiously, it talks about man:.

That's a good question and one for which I have no answer.  I'm happy to
follow whatever the consensus of implementations is, and if there isn't
one I guess I'll have to go see which RFC motivates the presence and
purpose of the double slashes after the colon.

> // This is then a bug in my xdg-open(1), as I failed to `open
> man:less` or `open 'man:less(1)'`.

Hmm, yes, that might be good to fix.  :)

> So I'd use man:.

Sounds good to me!

> > There is the question of what to do if a man page cross reference is
> > ambiguous, perhaps due to a plethora of installed pages on the
> > system.  (For example, I might have the Linux man-pages open(2) on
> > my system as well as the Open Group's open(2).  Typically this is
> > worked around by adding a suffix to the section, like open(2posix),
> > but I won't assume that every system-builder is so scrupulous; you
> > could have any number of man page hierarchies and expect $MANPATH to
> > sort them out[1]).  A difficulty is that man page sources find it
> > hard to know what disambiguating convention any particular system
> > has had to employ.)  I assume that whatever services "man:" URI
> > requests can present a disambiguating interface (or, less flexibly,
> > forces the "best" match on the user without notifying them of other
> > possibilities).
> 
> I think I didn't understand this (nor the text below).  What's the
> responsibility of groff(1),

That's the beauty of separation of concerns here; it doesn't have much.
All it needs to do is format a URI.  _Handling_ that URI, by launching a
Web browser or whatever, is utterly outside its bailiwick.

> and why does it need to know how to disambiguate anything?

It doesn't, but it's reasonable for URI interpreters to expect groff
(the system) to deliver as much information as is reasonably necessary
for them to do their job.

> I don't know where man(1) ends and groff(1) starts,

Broadly, man(1) locates man page documents given search parameters of
some kind (usually a single word), and groff renders formatted text from
them.

> but I think groff(1) should just interpret the URI

Oh, no!  I don't want to be in that business and groff doesn't have to
be.

> and pass it to man(1)

Not necessary.  groff isn't going to be launching man.  By the time a
man page is rendered, everything in the groff pipeline (groff(1) itself,
troff, and the output driver--grotty(1) being the one under discussion)
have already exited.  That's right and proper.

For this OSC 8 feature, the thing that will do the launching will be the
terminal emulator.  When testing this with gnome-terminal, for example,
I rendered grotty(1)'s own man page in the terminal.

$ ./build/test-groff -rU1 -T utf8 -man \
    ./build/src/devices/grotty/grotty.1

This will render the whole document without paging, so you'll end up
with the "See also" section at the bottom of your terminal window.  In
gnome-terminal, if you hover over the spelled-out URL for ECMA-48 or the
title of Egmont Koblinger's Gist, tooltips with the URLs will pop up.
If you right-click over the same text, a context menu pops up, and the
first item (for me) is "Open Hyperlink".

Similarly, when we hook up man page cross references to this feature,
we'll get a similar context menu for "man" URIs.

You can preview the feature like this.

$ printf 'Read \033]8;;man:grotty(1)\033\\grotty(1)\033]8;;\033\\!\n'

(Be careful to copy and paste that exactly.)

That's gnome-terminal solving the problem for us.

> which as you said is the librarian and should be the one who already
> knows where to search for the page (something like the resolver for
> this URI?).  So maybe groff(1) should just call `man 'open(3posix)'`
> for `man:open(3posix)` or `man open` for `man:open`, and let the
> librarian do librarian things.

No, groff has even less responsibility than that.  Its job is to format
a URI correctly and inform the output device, by whatever means it
supports, that it is receiving one.  That's what OSC 8 is for
EMCA-48-supporting terminals.

Is this clearer?

Regards,
Branden

signature.asc
Description: PGP signature