Add support for textDocument/documentLink request

[jwortmann]

Is this useful? Tested with LSP-TexLab:

A strange (or maybe just inaccurate) thing in the LSP specs is that a "document link"

links to an internal or external resource, like another text document or a web site

but the type for DocumentLink.target is DocumentUri, and not the more general URI (they both are defined as string though).

---

Initially I figured it might be good to make the links available in the right click context menu, similar to what Default/open_context_url.py does for website links, and to run the request only on demand when you open the context menu. But then we can't show the underlines for the links, and it would probably make the context menu very slow (I don't know if it would even be possible to run the request from the sublime_plugin.TextCommand.is_enabled() and wait for a response). So I guess to run the request in the background after text changed and show the link in a hover popup (like what VS Code does) is better and looks nicer.

---

TODO

• Add support for documentLink/resolve (when the "target" is not provided in the initial response)
• Maybe add some tests

Questions

• Are the style options useful? Is the default value good?
• Do we need an additional mouse binding (Alt + click) like in VS Code to directly open the link?

[rwols]

Awesome work @jwortmann. I do see that the "follow link" link is being positioned incorrectly with respect to the CSS? See screenshot below.

(for clangd one doesn't really need textDocument/documentLink because "goto definition" also opens the link to the #include)

Couple of boring questions:

• Should "Follow Link" also go into the "Goto" menu of the menu bar?
• Should "Follow Link" also go into the context menu when you right click a link?
• I think some users may want to key-bind this functionality. Maybe add a commented-out example keybinding?
• I fear that some users may get confused by the (default) blue underlines because those are also used (by default) as hints/info diagnostics. The OpenUri package uses an arrow emoji for an additional hint that the text is a link that you can follow. Do you think that such an arrow emoji would help? cc @jfcherng

[jwortmann]

Thanks for the feedback. I will try to fix the CSS alignment in the popup, but it is a bit inconvenient, because if I add padding, it doesn't look nice if the link is the only content of the popup. And probably needs some tweaking dependent on whether users have disabled the "show_symbol_action_links".

(for clangd one doesn't really need textDocument/documentLink because "goto definition" also opens the link to the #include)

Yes, it is the same case for LSP-TexLab. In general "document links" and "goto definition" seem to have overlapping functionality. I would guess that the "document links" are supposed to allow a distinct UI presentation for links in the source code, like the underlining or a popup on mouse hover.

* Should "Follow Link" also go into the "Goto" menu of the menu bar?

Added.

* Should "Follow Link" also go into the context menu when you right click a link?

Hm, not sure if this is necessary, because there is already the popup on mouse hover and I think navigation via this popup is faster than using right click and then selecting a sub-menu entry of the context menu.

* I think some users may want to key-bind this functionality. Maybe add a commented-out example keybinding?

Also done. If you want, you could add a mouse binding too:

// Default.sublime-mousemap
[
    {
        "button": "button1", "count": 1, "modifiers": ["alt"],
        "press_command": "lsp_open_link"
    },
]

It works fine for the links, but unfortunately this example with "Alt + click" would take priority over (and therefore disable) the built-in ability of subtractive selections (Windows & Linux) or column-wise selections (macOS).

* I fear that some users may get confused by the (default) blue underlines because those are also used (by default) as hints/info diagnostics.

It is not necessarily blue, the color depends on whatever the color scheme uses for the markup.underline.link scope. And the underlining with this color just reflects the standard highlighting of internet links (and some other links) in various syntaxes and color schemes, for example in Markdown, JavaDoc, C# comments etc.
The built-in color schemes all have them underlined.

And the diagnostics for info & hint are dotted, so it should be easy to distinguish those. What we perhaps could do, is to use no underline ("none") as default value for the "link_highlight_style" setting?

[jwortmann]

Any opinions about the default value for the link style? I'm undecided now, or even slightly lean to remove the underlining ("none"). I think as soon as you discover what your language server treats as links, the underlining provides little value. But maybe I'm biased, because it doesn't look very nice in my own color scheme.

---

By the way, Dockerfiles are an example where the links provide an actual feature not covered by "Goto Definition". For example in

FROM debian:latest

the link on debian will take you to the corresponding Docker website, and there is no "Goto Definition" available.

[rchl]

Since the work to implement this feature was made, I think the results should be easily discoverable by the user. Otherwise it's kind of a dead feature. So personally I think we should keep the default underline.

[rwols]

Looks good to me

[rwols]

By the way, Dockerfiles are an example where the links provide an actual feature not covered by "Goto Definition"

I just noticed another example is LSP-json for schema files, where you can do a "follow link" on a $ref, very nice!