manpage builder: emit OSC 8 hyperlinks via groff

[krobelus]

Hyperlink URLs are not included in man output, only link titles are.
Configuration option man_show_urls allows to append the URL but that
doesn't seem to work well; URLs can be truncated by line wrapping.
Also, long links can break the flow of reading.

Let's distinguish links with the OSC 8 escape sequence. This turns
the link title into clickable link if the terminal supports this
feature.

This relies on a feature that was introduced by groff 1.23.0
(2023-07-05), see https://lists.gnu.org/archive/html/groff/2021-10/msg00000.html.

[picnixz]

I'll let you remove the magic attribute and think of a way to do it with the version info. Maybe you can add that in the documentation of the manpage builder (the RST one) where you recommend to check for Sphinx version to know whether it supports or not OSC 8.

[krobelus]

Sorry I forgot to push yesterday. This should work.

Maybe you can add that in the documentation of the manpage builder (the RST one) where you recommend to check for Sphinx version to know whether it supports or not OSC 8.

I think the info in the changelog makes it obviuos enough

[picnixz]

I think the info in the changelog makes it obviuos enough

Yes, that's right actually.

[picnixz]

I'll wait for the checks to finish and we're good ! thank you in advance !

[grubert]

several problems

• long URLS ... not if using OSC8
• if using OSC8 one only sees the URL if moving the mouse over the linktext
• if using OSC8 and the terminal does not support it, one does not see the link at all
• are document local references possible with OSC8

therefore docutils 0.21rc1 renders the references in text,
i tried to make it look like mandoc output

this would allow moving long URLs at the end of the paragraph

[picnixz]

@grubert Thank you for your insights !

I'm sorry but I did not understand "long URLS ... not if using OSC8". Do you mean that long URLs are not well-supported even using OSC 8 ?

are document local references possible with OSC8

I assume that you are asking whether they are supported or not, right? @krobelus do you know about that? If not, I would suggest adding OSC 8 sequences only if the URI is a true URL (and not a local reference).

if using OSC8 and the terminal does not support it, one does not see the link at all

Oh, I did not know about it. I thought that the link would simply be rendered (without being clickable). @krobelus Can you confirm that Sphinx still renders the link as text if OSC 8 is not supported?

@krobelus Maybe we should revert this commit and patch it differently (or follow docutils 0.21rc1?)

[krobelus]

on which terminal are you seeing the problems caused by OSC8 anchors?
I don't expect a behavior change for real-world terminals

[krobelus]

if using OSC8 and the terminal does not support it, one does not see the link at all

Yes but that was already the case before adding OSC8. Only the link title was shown.
I tested with st which is a terminal that doesn't support OSC8 and the output is unchanged.

are document local references possible with OSC8

I assume that you are asking whether they are supported or not,
right? @krobelus do you know about that? If not, I would suggest adding
OSC 8 sequences only if the URI is a true URL (and not a local reference).

How can I create a local reference that has the refuri property?
I tried :ref:`some-local-anchor` but that doesn't seem to have it.
I'm not sure if a refuri can be relative.

if using OSC8 one only sees the URL if moving the mouse over the linktext

Yes, that's what gnome-terminal does for example.
What do you expect to see instead?
Perhaps that URLs are shown as part of the normal text?

If so, that's not a problem of OSC 8 anchors, although I recognize the problem.
Showing URLs as part of the text can be nicer, for example when I'm viewing man pages in my editor which does not support OSC8 yet (plus it means I can search for parts of the URL etc)

There is a configuration knob (man_show_urls) to show URLs inline but I don't think it works well for all cases (it applies to all URLs).

this would allow moving long URLs at the end of the paragraph

Yeah, I think rendering

`This is a link <https://example.com>`_
followed
by
a
long
paragraph
of
text.

as

This is a link[1]
followed
by
a
long
paragraph
of
text.

[1]: <https://example.com>

would be nice and I might use that --
on top of OSC8 anchors, not replacing them.
The anchors allow terminals to interact with the link which is unrelated of where we put the URL text.

[krobelus]

I see that docutils used to use .UR and .UE and ran into problems.
I think that's because these markers are not as powerful as the "tty link" device
control command.

For example

\X'tty: link https://example.com' The Link Title <https://example.com> \X'tty: link'

Is equivalent to <a href="https://example.com">The Link Title %3Chttps://example.com%3E</a>.

Which is not possible to express with UR/UE I think.

So this example renders URLs as (title <url>) which is what both Sphinx's man_show_urls and docutils 0.21rc1 do.
But additionally it also tells the terminal that the entire thing is a hyperlink, which is a strict improvement so I think docutils should probably do that too.

As for whether man_show_urls behavior should be the default, I don't know, it depends on what users expect.

And yeah, as it stands Sphinx needs to override depart_reference (unless we can delegate everything to docutils).