Specific helper for RStudio code execution links

[hadley]

e.g.:

  link <- function(code) {
    cli::style_hyperlink(code, paste0("rstudio:run:testthat::", code))
  }

Main difference with style_hyperlink() is that it's only activated if in RStudio.

[hadley]

Paired with inline formatter like .run. I'm pretty sure this this should be different to .code since that often contains unrunnable snippets.

It may need to be like .href because while we want to match the code clicked and run, we made want to vary the details, e.g. we show snapshot_accpet("foo.R") but we run testthat::snapshot_accept("~/documents/testthat/tests/_snaps/foo.R").

[gaborcsardi]

Yeah, unfortunately, we are creating a (sub)DSL for this, but there isn't really another way. I'll write some DSL ideas in this issue later...

[hadley]

Another case where this will be important is for pkgdown — we'd want to render links to websites, but not to local files or to run code.

[hadley]

See complete list in https://github.com/rstudio/rstudio/issues/11273#issuecomment-1153627945

[lionel-]

For IDE agnosticity, I think this is now ide:run: and should be guarded by nzchar(Sys.getenv("R_CLI_HAS_HYPERLINK_RUN")) (see #499). But @romainfrancois should confirm this.

[gaborcsardi]

Final list of link types: https://github.com/rstudio/rstudio/issues/11273#issuecomment-1156193252

[gaborcsardi]

Here is the plan.

Update current styles

• [x] {.email email} creates mailto: links
• [x] {.file file} and {.path file} create file:/// links
• [ ] {.file file:line:col} for line and column number
• [ ] {.fun pkg::fun} creates links to help, and formats pkg::fun as a function.
• [x] {.url url} creates a hyperlink
• [ ] TODO: Should they use link text for names? Probably not.

Links to help (new)

• [ ] {.help pkg::fun}
• [ ] {.help pkg::fun link text}
• [ ] TODO: topics vs functions?
• [ ] TODO: how to format the link text?

Hyperlinks, possibly with link text (new)

• [ ] {.href url} is equivalent to {.url url}.
• [ ] {.href url link text} create a hyperlink with link text, url cannot contain a space character. If url is not a literal, it is best to use as_href() on it, to make sure that it does not contain a space.
• [ ] {.href {url}} uses the name(s) of url as link text

Running code (new)

• [ ] {.run expr}
• [ ] {.run expr code} show code (typeset as {.code}) and link to running expr.

Links to vignettes (new)

• [ ] {.vignette pkg::name}
• [ ] {.vignette pkg::name text}
• [ ] TODO: what is the default link text? How to format it?

Notes

If links are not supported, then cli just prints the url, path, etc.

If there is also link text, then it prints the link text and in parens the URL, file name, etc.

[gaborcsardi]

I considered having {.url url link text} instead of a new {.href} style, but URLs are now styled by adding <...> currently, and that does not look good if there is link text, so it is better to have a new {.href}` style.

[gaborcsardi]

Auto-linking existing styles

They keep formatting. It is not possible to use a different link text with them. We could add link text support, but theming is applied to the result of these tags, and it would look weird for link text. (I.e. if there is link text you don't want to append () to the function name, etc.)

N	Goal	Input	Links to (link text is always the verbatim content, styled)
1	auto-link emails	{.email [email protected]}	mailto:[email protected]
2	auto-link file	{.file path/file}	file:///abs/path/dile
3	auto-link file with line and column numbers	{.file /abs/path:line:col}	file:///abs/path:line:col, params = list(line = line, col = col)
4	auto-link function	{.fun pkg::fun}	x-r-help:pkg::fun
5	mention function w/o package	{.fun fun}	no link is created for this form
6	auto-link url	{.url url}	url

New styles to create links

These all have link text support, via the [text](link) markdown syntax.

N	Goal	Input	Link text	Links to	Non-link form
7	link qualified function name to help	{.help pkg::fun}	{.fun pkg::fun}	x-r-help:pkg::fun	{.fun ?pkg::fun}
8	link to function with link text	{.help [text](pkg::fun)}	text	x-r-help:pkg::fun	text ({.fun ?pkg::fun})
9	link to topic	{.topic pkg::topic}	pkg::topic	x-r-help:pkg::topic	{.code ?pkg::topic}
10	link to topic with link text	{.topic [text](pkg::topic)}	text	x-r-help:pkg::topic	text ({.code pkg::topic})
11	link url	{.href url}	{.url url}	url	{.url url}
12	link url with link text	{.href [text](url)}	text	url	text ({.url url})
13	link running expr	{.run expr}	{.code expr}	x-r-run:expr	{.code expr}
14	link running expr, show code	{.run [code](expr)}	{.code code}	x-r-run:expr	{.code expr}
15	link to vignette	{.vignette pkg::name}	pkg::name	x-r-vignette:pkg::name	{.code vignette(pkg::name)}
16	link to vignette with link text	{.vignette [text](pkg::name)}	text	x-r-vignette:pkg::name	text ({.code vignette(pkg::name)})

[hadley]

Suggestions for non-link forms:

• For documentation link, add ? in front of the proposed text?
• For urls, surround in <> (I think maybe only "link url" is missing that?)
• For vignette, make it vignette(name, pkg)?

[gaborcsardi]

Sounds good. URLs are already in <>, that's part of the default theme.

[gaborcsardi]

I updated the table above.