12.2 Link handling

The buffer can contain clickable links. These can be created implicitly, by recognizing a URL or other pattern in the buffer. Links can also be created explicitly, using a special escape sequence, or by emitting HTML.

There are two kinds of links:

• A regular link displays in the “normal” link style (typically blue text with underline). (If the class attribute includes the word plain then no underline is added, but normal link styling applies otherwise.) A click opens a browser window/tab or an application, as described below, as does right-click (context menu) and then selecting Open Link.
• A subtle link is only active if you also hold the the Ctrl key; you can also use the context menu. This is to reduce accidental clicks. Links created implicitly using pattern-matching are subtle, and additionally have no special styling except when mouse hovered. Internally, a subtle link is distinguished by its class attributes containing subtle.

Automatic creating of links

DomTerm will scan the output for text that "looks" like a URL or a mail address, and turn it into a clickable “subtle” link.

The links are only visible when you hover the mouse over them. (This is because what is a link is a guess, and so we don’t want to clutter the display with links that aren’t explicitly created.) You can change the styling: The class attribute for these links contains both matched (because they are generated by pattern matching), and subtle (because you don’t want them styled except when hovering).

By default the only recognized URL schemes (the part before the colon) are http, https, ftp, file, and mailto. If the preference open.file.application or open.link.application mentions a URL scheme in a condition (see below) that scheme is added to to the set of recognized URL patterns.

A string starting with www. is treated as it it starts with http://www.. A string that looks like an email address (matching the regex pattern ^[^@]+@[^@]+\.[^@]+$) is treated as if it starts with mailto:.

Many programs emit error messages that start with filename:line: or filename:line:column. These are turned to links of the form file:/filename#position=line or file:/filename#position=line:column:. If filename is relative, it is made absolute if the process directory is set. (The directory can be set using the escape sequence "\e]7;file://hostname/directory\a". See the shell function print_path_url above.) You can specify an editor or other handler for these special links, as described below.

Specifying handlers for clicked links

If you click on a link (with a full URL, not one starts with ‘#’), then the request is sent to the backend, which will invoke an appropriate viewer, such as a browser.

Which application to use depends on two preference variables: open.file.application and open.link.application. Both are conditional lists of templates, separated by semi-colons or newlines. When opening a file: link both template lists are used (first open.file.application is tried then open.link.application); otherwise, only open.link.application is tried. Here is the default, in settings.ini multi-line format:

open.file.application =
 |{in-atom}{with-position|!.html}atom
 |{with-position|!.html}emacsclient
 |{with-position|!.html}emacs
 |{with-position|!.html}atom
open.link.application =
 |{!mailto:}chrome
 |{!mailto:}firefox
 |default

The following templates are supported:

emacs

Invoke the Emacs editor on the specified file and optional (line,column)-position. Equivalent to "emacs %+P '%F' > /dev/null 2>&1 &".

emacsclient

Ask the Emacs server to open en editor window on the specified file and optional (line,column)-position. Equivalent to "emacsclient -n %+P '%F'".

atom

Invoke the Atom editor on the specified file and optional (line,column)-position. Equivalent to "atom '%F'%:P".

firefox

chrome

google-chrome

Open the specified web browser (chrome and google-chrome are the same). Equivalent to the browser’s executable path followed by " '%U'".

default

browser

Open the default browser or other registered application.

{condition}template

{condition|condition...}template

Skip the template unless one of the conditions succeeds. There can be multiple {condition}-groups, in which cases all must succeed.

A condition can be one of the following:

in-atom

Succceeds if using atom-domterm.

with-position

Succceeds if the URL ends with #position=position.

scheme:

Matches if the URL-scheme is scheme. This is the part before the first colon, such as http:. The default uses !mailto: to supress using firefox or chrome for email addresses.

.ext

Matches if the URL has an "extension" matching ext. For example .html matches html files.

!condition

Suceeds if condition fails and vice versa.

custom template

Using ‘%’-escapes to create a system command. The following escapes are supported:

%U

Substitute the URL (the href attribue of the link).

%P

Substitute the value of the (line,colon) file position from the #position=position or the URL.

%:P

%+P

Same as respectively :%P or +%P if the position is specified in the URL. Expands to nothing otherwise.

%F

Only succeeds for file: URL, which is converted to a file name. You should use quotes: command '%F'.

%%

A literal ‘%’.

After expansion, if there are any unquoted shell special characters (any of <>|&$), then the command is executed by a shell. Otherwise, it is executed directly (in the background, as a daemon).