Miscellaneous tips

Copy and Paste

In character mode the “standard” keyboard shortcuts for copy and paste (ctrl-C and ctrl-V) are sent to the backend program. So instead DomTerm uses ctrl-shift-C to copy the selection to the clipboard, and ctrl-shift-V to paste the contents of the clipboard.

Some front-end also have menu entries for copy and paste.

The selection is copied as both plain text (text/plain) and formatted HTML (text/html) in case the receiving application can paste the latter. The HTML is slightly cleaned up from the raw DOM (in the same way Save as HTML does). Note that only inline styling is copied; no attempt is made to merge in style rules from stylesheets.

The Copy as HTML command places the formatted HTML in the clipboard as text/plain so you can paste the HTML into a text editor.

Front-end support: Middle-button paste (i.e. clicking the middle button pastes the contents of the selection, rather than the clipboard) works on qtdomterm, and chrome-based browsers. It does not work in a Firefox browser window.

Save the console contents as HTML

Use the keyboard shortcut ctrl-shift-S to save the contents of the DomTerm console as an HTML file. Both qtdomterm and the Electron front-end also offer menu entries for this.

The saved file should be viewed with various css stylesheet files in the hlib subdirectory. You can create a symlink to the hlib subdirectory in the DomTerm distribution. The saved file also optionally makes use of some JavaScript, in the same directory. The JavaScript isn’t essential, but it enables features like hide/show buttons and dynamic line-(re-)breaking.

Images will preserve their URLs. Relative URLs may need to be fixed, but absolute ones should be fine. “Embedded” images using a data: URL (including those loaded with the image sub-command) will be saved embedded, and Just Work.

The resulting file is actually an XHTML file, so you can use XML tools to extract parts from or transform the output.

Front-end support: The qtdomterm and the Firefox/XUL applications bring up a file chooser, and let you save the file in any writable directory. Other front-end bring up a prompt pop-up and only allow saving to the Downloads area. The JavaFX front-end currently does not support saving.

Note that if DomTerm is running in a browser window, the browser’s Save page as ... command is not useful. It will save the original bare web page, before any DomTerm interactions or other JavaScript modification.

Adding domterm or qtdomterm to the desktop

On Gnome or KDE

Copy domterm/domterm.desktop or qtdomterm/qtdomterm.desktop to either /usr/share/applications (if domterm is installed in /usr/bin and you want it accessible to everyone), or in ~/.local/share/applications (if you only wish to make accessible to a single user).

Environment variables set

The DomTerm back-ends set various enviromnent variable when they start up a process.

TERM is set to "xterm-256color". COLORTERM is set to "truecolor".

The DOMTERM variable is set to a semicolon-separate list of information about DomTerm and how it was invoked. The specific list is subject to change.

An example when running on qtdomterm:

QtDomTerm;version=0.80;tty=/dev/pts/3

The Electron front-end may yield:

version=0.80;electron=1.3.13;libwebsockets=2.1.1;tty=/dev/pts/1

Checking the DOMTERM variable is a simple way to check if we’re running in a DomTerm terminal. It is not foolproof, as explained here.

WINDOWID is not set - in fact qtdomterm unsets it. There seem to be some problems setting it with Qt. This variable is not set by Wayland.

Various programs

ls - showing files as links

Newer versions of the GNU ls programs support a --hyperlink option that creates a file: link for each filename. The escape sequence is also recognized by gnome-terminal, and should be harmless for other xterm-like terminals. Consider adding this to your shell init file:

case "$TERM" in
  *xterm*) alias ls='ls --hyperlink=auto';;
esac

gnuplot

The gnuplot graphing application has builtin support for “printing” graphical output to the DomTerm console

pandoc Printing markdown and other document types

The pandoc program can convert documents between multiple document formats. To view a Markdown document doc.md you can do:

pandoc -t html doc.md | domterm hcat

You might optionally use the --self-contained flag to force images to be “inlined” in the terminal output:

pandoc -t html --self-contained --metadata pagetitle=dummy doc.md | domterm hcat

(The --metadata pagetitle=dummy is to silence an annoying warning.)

Showing man pages as html

To view the bash man page inline you can do the following. This works best with Automatic Pager set.

man -Hcat bash 2>/dev/null|domterm hcat

Moving input cursor using mouse clicks

Many interactive programs support simple editing of the current input line. There are a number of libraries for this (for example as GNU readline), that support moving the cursor using arrow keys but do not handle the mouse.

In “readline mode” a mouse click is translated into arrow key presses that should move the cursor to the clicked position, assuming the interactive program understands arrow keys.

There are two ways to enable readline mode for a mouse click:

• If the Alt key is pressed at the same time as the mouse click.
• If both the mouse click target and the current cursor position are in the same input-line group (i.e. they’re in the same <div> element with a class attribute specifying input-line).

  To create an input-line group you set the appropriate escape sequence ‘\e[15u’ in the end of the prompt string, as show in tip for bash shell prompt. If using an input editor library that handles multi-line input commands (such as JLine3), use the escape sequence ‘\e[15;2u’ instead.

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 link. To reduce accidental clicks, these automatic links are only active if you also hold the control key; you can also use the context menu.

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 plain (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:.

Programs that emit explicit links (using HTML escape sequences) can specify the class as subtle to indicate links that should be more subdued than default link styling. (A subtle link shows with the normal link color (by default blue), but underlining is only shown on mouse hover.)

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).