[manpage] don't emit OSC 8 hyperlinks for anchor references (#12108)

[krobelus]

A reference like :ref:`Some other page <some-other-page>` results
in a refuri "#some-other-page". This does not seem useful to readers
of the man page. It is especially unhelpful when using a terminals
that implements a hint mode for selecting links -- the extra links
add noise, making it harder to select the interesting ones.

While at it, relax the restriction that "man_show_urls" is limited
to mailto/http/ftp URLs; I don't see why other protocols shouldn't
be allowed.

Follow up to #12108

I also confirmed that even with docutils 0.21 we do not need to
override depart_reference because we already skip reference nodes.

[picnixz]

mailto/http/ftp URLs; I don't see why other protocols shouldn't
be allowed.

I still want to restrict those protocols to avoid unexpected actions if you click on them (see https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml). I bet any URI scheme can be insecure but I would prefer restricting to the "well-known" schemes and the most common ones. On the other hand, if you want to handle more protocols, I think we can make it a configuration value.

[krobelus]

It's fair enough that clickable links should be restricted to safe ones, especially since we're running in a different security context than a browser. I'll do that.
But I think man_show_urls specifically should show any link, no matter the protocol, because by showing the exact URL there should be no surprise.
I'd like to avoid a configuration value for most reasonable use cases - look at what happened to man_show_urls - at least pre-OSC 8 it should have been the default but it wasn't and pretty much no one uses it (and it has some usabililty problems like the URL being hard-wrapped though I'm not sure it's possible to avoid that).

[picnixz]

I'd like to avoid a configuration value for most reasonable use cases

That's a sound argument. So maybe you could store the allowed protocols at the class level and users could simply override that field in extensions (without needing a configuration value).

[krobelus]

I don't think I agree. That being said, it's the existing behavior (however weird it is) and I don't have a concrete motivation to want to change it. So this is fine by me, can revisit this later.

[picnixz]

Actually, it's dumb from me. The if would be equivalent to is_safe_to_click, so applying my suggesting is the same as not having your PR at all.

Now, the if-body is doing some processing for mailto links and cuts the URI. After, we check if the URi is still empty or not and emit OSC if needed. I'd suggest doing something different and perhaps more flexible:

• Check whether you are using an URI scheme or not: if so, just keep the current behaviour. In particular, you cannot be an achor if you are using an URI scheme.
• For anchor references, do nothing.

[krobelus]

I'm not 100% sure what you mean, do you think it's fine that arbitrary URIs remain clickable?

I don't have a strong opinion on that one. But better safe than sorry I guess, which is why this PR disables them.
I mainly care about fixing anchor-references (by not showing them at all), and making man_show_urls show all non-anchor URIs as text

Here are the cases, starred are the ones fixed by this current PR

refuri	clickable	shown with man_show_urls
https:///example.com	yes	yes
gopher:///example.com	no*	yes*
#local-ref	no*	no

[picnixz]

Oh, ok, your approach is better. If this is how this is rendered, then I'm fine ! (it was just hard to imagine the things since I don't see a visual example).

[krobelus]

Fixed a problem with empty URLs and man_show_urls.

Give file links like link-to-file <../somefile>`__ and man_show_urls=True this PR makes the man page build also render the file path. I guess we could remove that (and only show URIs that start with somescheme:) but I don't know any case where this is relevant.