Re: We have OSC 8 terminal hyperlink support now

[Alejandro Colomar (man-pages)]

Hi, Branden and John!

On 10/2/21 4:57 PM, G. Branden Robinson wrote:
> 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.

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:.  See uri(7), but I'll 
paste some important parts here:

[
DESCRIPTION
        [...]
   Usage
        [...]

       man - Man page documentation

       man:command‐name
       man:command‐name(section)

       This refers to local online manual (man)  reference  pages.
       The  command name can optionally be followed by a parenthe‐
       sis and section number; see man(7) for more information  on
       the  meaning  of  the  section numbers.  This URI scheme is
       unique to UNIX‐like systems (such as Linux) and is not cur‐
       rently registered by the IETF.  An example is <man:ls(1)>.

        [...]
NOTES
       Any  tool  accepting  URIs (e.g., a web browser) on a Linux
       system should be able to handle  (directly  or  indirectly)
       all  of  the schemes described here, including the man: and
       info: schemes.  Handling them by invoking some  other  pro‐
       gram is fine and in fact encouraged.

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

]

So I'd use man:.

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

I think I didn't understand this (nor the text below).  What's the 
responsibility of groff(1), and why does it need to know how to 
disambiguate anything?  I don't know where man(1) ends and groff(1) 
starts, but I think groff(1) should just interpret the URI and pass it 
to man(1) 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.

Regards,

Alex


> 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


--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/