Re: We have OSC 8 terminal hyperlink support now

[G. Branden Robinson]

Hi, John!

At 2021-10-02T23:20:06+1000, John Gardner wrote:
> I know it's probably a bit early for this discussion, but somebody on
> GitHub raised a good question
> <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda#gistcomment-3914435>
> :
> 
> > Why x-man-page? dnf reports that yelp & khelpcenter provide man:// -
> > but has no providers for x-man-page://

I was unaware of "x-man-page" as a URI schema.  "man", however
unofficial and unblessed by WHATWG or whomever, has been used in
production systems for decades.

> He was referring to an example I gave of a hyperlinked man page
> reference ( x-man-page://awk.1), which is supported on macOS
> (Terminal.app and iTerm2), but not universally
> <https://github.com/Alhadis/Roff.js/blob/ba9b904b944c028033b4b4f584521436a34a5d57/lib/utils/general.mjs#L15-L23>.
> Which invites the question—how are we going to hyperlink man page
> references, specifically?

My intent was to have the `MR` macro generate URIs of the form
"man:ls(1)"; it's well known, widespread, bears a syntax that is easily
deciphered by people only passingly familiar either with URIs or man
page cross references, requires only information that will already be
present in the page (what people already give as arguments to .IR or
.BR) and most importantly throws the responsibility of locating any page
matching that cross reference far away from us.  man(1) programs do a
fine job of locating pages given exactly this information.

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).

The foregoing is why I have adopted the practice of calling man(1) the
man page "librarian".  My feeling is that anything that services a
"man:" URI adopts a similar responsibility.

It would be tractable to expose a man(7) string that man(1) programs can
define to smuggle information to the formatter at the time a page is
rendered to help disambiguate any cross references that come back out,
but I'm having trouble thinking of a way that would actually help--if
man(1) knows such a thing, why tell the formatter about it at all?

Regards,
Branden

[1] For example, I had to compile and install a more recent version of
    less(1) to test out my OSC 8 changes.  Thus I wound up in the
    following situation.

    $ man -aw less
    /home/branden/share/man/man1/less.1
    /usr/share/man/man1/less.1.gz
    /usr/share/man/man3/less.3perl.gz

signature.asc
Description: PGP signature