Feature request: Hyperlinks

[egmontkob]

Recently two popular terminal emulators, GNOME Terminal and iTerm2 have implemented a brand new feature: explicit hyperlinks.

Unlike the existing functionality of most terminal emulators of automatically detecting URLs that appear onscreen, this time it's like hyperlinks on web pages: the link target is explicitly specified by the OSC 8 escape sequence and the visible text can be an arbitrary piece of text.

We believe this feature can provide a noticeable productivity boost for plenty of users, and hence we're hoping to get some widespread recognition and support, in which tmux joining the game would be a key factor!

Ideally tmux would make its presence transparent to the user and make sure hyperlinks work exactly as if tmux weren't in the game. This includes autogenerating or mangling the id parameter in some trivial way, see the docs linked below for why and how, but that's a piece of cake. The toughchallenging bits is probably coming up with a memory-efficient way of storing a target URL for some of the character cells.

Please see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda for details about this feature.

[nicm]

I'm not going to implement this but if you come up with a patch I'll look at it, although it will need to be kept fairly simple. It can just use the existing extended cells mechanism used for UTF-8. Also there will need to be some way to detect it even if it just means inventing a terminfo capability. On 4 May 2017 10:11 pm, "egmontkob" <notifications@github.com> wrote: Recently two popular terminal emulators, GNOME Terminal and iTerm2 have implemented a brand new feature: explicit hyperlinks. Unlike the existing functionality of most terminal emulators of automatically detecting URLs that appear onscreen, this time it's like hyperlinks on web pages: the link target is explicitly specified by the OSC 8 escape sequence and the visible text can be an arbitrary piece of text. We believe this feature can provide a noticeable productivity boost for plenty of users, and hence we're hoping to get some widespread recognition and support, in which tmux joining the game would be a key factor! Ideally tmux would make its presence transparent to the user and make sure hyperlinks work exactly as if tmux weren't in the game. This includes autogenerating or mangling the id parameter in some trivial way, see the docs linked below for why and how, but that's a piece of cake. The toughchallenging bits is probably coming up with a memory-efficient way of storing a target URL for some of the character cells. Please see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3c b5feda for details about this feature. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#911>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASkc20gGssuCPv3jBNKFAEDJjdQzzWZks5r2j7ygaJpZM4NROXG> .

[ljfranklin]

@egmontkob @nicm would you expect the escape passthrough sequence (\033Ptmux;\033<whatever>\033\\) to work with explicit links if the parent terminal supports links?

[egmontkob]

@ljfranklin Nope, absolutely not.

[nicm]

Are any applications using this yet?

…

On Wed, 29 Aug 2018, 09:03 egmontkob, ***@***.***> wrote: @ljfranklin <https://github.com/ljfranklin> Nope, absolutely not. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#911 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASkc7BLaOusY2WWbyIW0TJqeHKfwp9mks5uVkrDgaJpZM4NROXG> .

[lucaswerkmeister]

Are any applications using this yet?

Yes, for example systemd uses this starting with v239 (see the NEWS file and systemd/systemd#8767 for details) to format hyperlinks to manual pages and configuration files.

[nicm]

I guess it will still wait to see if some of the major terminal applications pick it up. irssi/weechat would seem to be the most obvious.

[egmontkob]

@nicm Please see the originally linked page for a list that I try to maintain up to date.

@lucaswerkmeister Thanks a lot for the systemd info, I didn't even know they had it on their roadmap. Added to my page.

[bl33pbl0p]

@egmontkob

You know, instead of causing so much churn everywhere to support hyperlinks, maybe do it the other way around that does not require every project to add such code? Acme from Plan 9 did it in the 90s, that was true hyperlinking, because the environment decided how it will treat the resource (and then use Plumber to decide based on rules whether it needs to go to the edit port or the browser port, for instance). Much more powerful, much less code, and allows for greater extensibility. That was also true hyperlinking because to support a new resource you just needed a new rule -- and you could hyperlink anything with anything (consider selecting an ISBN number and in Plan 9 and that led you straight to your browser, or just selecting main.c:32 that opens your text editor with the cursor on that line, it's just like pipes, the limit to extend it is unimaginable).

The fact that every project needs to add hyperlink specific code screams that this model you're pushing for is broken. The editor I write tomorrow needs to accomodate for such a scheme to work, whilst it should the environment accomodating (and in my example, that boils down to adding one rule to match on what is being sent to be opened). Ofcourse, you can't decide if you need Plumber or D-Bus for this, which is why it should be mechanism free, nor do you need to conform to a URI scheme like what freedesktop has. Good design is when you don't need to do much, and it just happens by itself, and it's not like this wasn't done before.

[egmontkob]

@bl33pbl0p

First of all, I don't think tmux's issue tracker is the right place if you have problems with the overall design. This issue is meant to track the spec's implementation in tmux. The spec itself also has its homepage. But as you commented here, let me respond here.

Apologies for my ignorance, I've heard about Plan 9, but never seen it, don't know what Acme is (its wiki page says it's a "text editor and graphical shell", doesn't seem like a terminal emulator to me), I have no idea what Plumber, edit port, browser port etc. are. But: I have an overall feeling that it's a substantially different notion from what a terminal (terminal emulator) on a Unix system is.

Good design is when you don't need to do much, and it just happens by itself

Generally I agree. This happens when the underlying infrastructure is built up in a way that lets you easily do whatever you want to do. It doesn't necessarily mean fewer code, though, it just means that most of the code you need is luckily already available underneath you and you can build upon, rather than having to write it yourself.

Could you please be more constructive, and show us: How do you think on top of where we started from (Unix systems, terminal emulators, escape sequences, some utilities just spitting output to stdout, some utilities handling the entire terminal emulator canvas using whatever screen drawing methods, etc.) this issue could have been addressed in a more elegant way?

[nicm]

How can I detect if the terminal outside tmux supports this?

[nicm]

Oh I see you have a section about that, although it is not terribly useful. Do iterm2 and gnome-terminal have unique escape sequences which report their version?

[nicm]

We can have a global tree of hyperlinks keyed by a uint32_t ID and store that ID in the grid_cell. Each pane can also have its own tree mapping any application-assigned IDs to the global ID. We can throw them away when the cells are scrolled out of the history or overwritten, but probably not worth the bother. Maybe just on RIS/E3/clear-history.

Presumably the hyperlink target has to also match for the external terminal to highlight, not just the ID, but would need to check. What happens with the history? If two separate applications print the same hyperlink with the same ID at separate points in the history and the user then scrolls up so they are both visible presumably the external terminal will highlight both - probably doesn't really matter and probably no realistic way to fix it anyway.

Would need to track the current tty state to make sure we do not send the hyperlink sequence unnecessarily.

Will need terminfo entries or some other way to detect, best probably something like Shl=\E]8;id=%p1%s;%p2%s\E\\ and Rhl=\E]8;;\E\\. Or just a flag would do perhaps. Or detect from the terminal versions, but that is a pain with !xterm.

[nicm]

We would need the pane tree to map (application ID, hyperlink) -> global ID not just the ID, in case two applications use the same ID for different hyperlinks.

No need to worry about alternate screen because all the global IDs would be stored in the cells so would be switched with everything else. If applications in the same pane use the same (ID, hyperlink) pair it should map back to the same global ID.

We should assign a new global ID for each new (ID, hyperlink) pair that is not in the pane tree where it is received. We can't reuse them across panes because multiple panes may have them visible on screen at the same time. So lookup in the global tree is only for writing to tty (ID from cell to hyperlink); pane tree is when OSC 8 is received to see if an ID already exists.

[egmontkob]

Presumably the hyperlink target has to also match for the external terminal to highlight, not just the ID, but would need to check.

Yes; at least that was my intent, and is the behavior in VTE. I cannot test iTerm2. From the gist: "Character cells that have the same target URI and the same nonempty id are always underlined together on mouseover."

If two separate applications print the same hyperlink with the same ID at separate points in the history and the user then scrolls up so they are both visible presumably the external terminal will highlight both - probably doesn't really matter and probably no realistic way to fix it anyway.

I agree it's not realistic. This is only relevant if these two are closer to each other than the terminal's size. IDs are mainly useful for fullscreen apps. Simple utilities probably just don't emit an ID; hyperlink cells that don't have an ID are only joined with the ones emitted in the same OSC 8 run.

(The way it is implemented in VTE: each time an OSC 8 without ID (but with non-empty hyperlink) is encountered, a new unique ID is automatically generated for this. This new ID also contains a semicolon if I remember correct, a character that cannot be part of the explicit ID due to OSC 8's syntax. This guarantees that the new autogenerated ID cannot accidentally clash with an explicit one. Of course tmux couldn't use this exact approach since it has to forward the generated ID to the host emulator, but it presumably mangles the IDs anyway (prefix with the pane ID or such), and then it could similarly pick some other prefix that's guaranteed not to conflict with these; or just go with some random that is highly unlikely to clash.)

---

Just FYI: There are two different ways tmux could leverage the OSC 8 feature. One is when it encounters an OSC 8 from the application running inside, and forwards it towards the host emulator. Another one is when it doesn't receive any, but receives a simple text that looks like a URL, however, with vertical panes, it won't be recognized by the host graphical terminal emulator as such. In this case tmux could help by recognizing it and converting to OSC 8. This latter one sounds more complicated, at least requires that tmux matches the visible contents of its panes against some (complex) regex and takes action on the match – not sure if tmux has anything like this at the moment. This is just a heads-up to keep it in mind for a possible future improvement, not a requirement by any means.

---

Adding support for feature detection is out of my radar at this moment. Both the terminfo approach and the asynchronous escape sequence response approach would suffer from several problems.

You can just emit OSC 8 and be pretty sure that the terminal emulator will either handle it according to the hyperlink specs, or ignore it. Or, if that's not the case for a certain emulator then apps emitting them break anyway even outside of tmux, tmux forwarding these escape sequences wouldn't make it much worse. I'm not sure about apps emitting OSC 8 hyperlinks, but I'd guess that it's an opt-in feature in them, not an out of box one (at least it's definitely opt-in in ls). That being said, you might introduce a config option to disable this feature, a simple kill switch for those encountering troubles.