Tips and solutions

This page covers various topics, and may evolve to a Frequently-Asked-Questions page.

Notes about “Front-end support” discuss how different front-ends may support some features differently.

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.

Browser quirks and limitions

(These can all change as browsers change or work-arounds are implemented.)

Middle-button paste: Works with Chrome and qtdomterm (on Linux); does not work on Firefox.

Exiting the inferior process can sometimes fail to automatically close the DomTerm window, due to browser security limitations. It currently works on Google Chrome, but not Firefox.

Saving the console display to a file in a browser may save to the browser’s “Downloads” area. You may be able to save the file elsewhere, depending on the browser and its settings.

Using line-editing mode with the brower’s builtin editor may exhibit various quirks.

Microsoft Edge does at time of writing not handle the tab-size CSS property, so on that browser tab characters are always converted to spaces.

Adding domterm or qtdomterm to the desktop

On Gnome or KDE

Copy domterm/qtdomterm.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 the normal way to check if we’re running in a DomTerm terminal. It is not foolproof, since you could (for example) spawn off an xterm, which would not reset the DOMTERM variable. To make it more robust, you can compare the output of the tty command or the ttyname function with the value specified after tty=. However, tty= might not be specified unless runnng under a pty.

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.

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:

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.

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 might want more subdued styling).

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

Useing ‘%’-escapes to create a susyem shell 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 ‘%’.