Settings

A setting is named value that controls how DomTerm works, depending on user preference or environment.

Settings can be global settings, or local settings. Global settings are specified in a setings.ini configuration file, and apply to all sessions and windows managed by a server. Local settings are specified on the command line (or in the future a GUI) and apply to the current command, session or window.

The settings that are active is the merge of the global and local settings, with the latter taking precedence.

Global settings from settings.ini file

User preferences for DomTerm are normally in the file .config/domterm/settings.ini in the user’s home directory. This location can be overridden with the --settings command-line option; otherwise the location is $XDG_CONFIG_HOME/domterm/settings.ini, where XDG_CONFIG_HOME defaults to $HOME/.config. (For compatibility reasons, $HOME/.domterm/settings.ini is also checked if $XDG_CONFIG_HOME is unset, but that may go away.)

(On WSL (Windows Subsystem for Linux) the file is c:\Users\USER\AppData\Roaming\DomTerm\settings.ini.) You can override this default with the -settings command-line argument. If the settings.ini is changed it is automatically re-loaded.

The syntax of settings.ini is a variant of the INI file format. A preference is written as:

keyword = value

For example:

window.geometry=800x600

Spaces before or after = are optional. A keyword should be a sequence of letters, numbers, periods or hyphens. The value is almost any sequence of characters (depending of the keyword), up to end of the line.

Multi-line values are written as an empty line following the ‘=’, and then one or lines starting with a single space followed by ‘|’. For example:

style.user =
 |div.domterm { --background-color: azure }
 |div.domterm-spacer {background: none }

In this cases the resulting value has two lines, with the two-character prefixes ‘ |’ removed.

Comment lines start with # in the first column. Comment lines and all-blank lines are ignored.

Local settings from command line

On the domterm command line, you can specify a local setting with an argument that contains an equal sign (=) and that does not start with a hyphen (-). A settings argument is specified with other options before the command, if any. For example:

domterm style.dark=yes new bash

Command-line settings are used for the current command, including creating a new session or window.

To change local settings for a current window, you can use the domterm settings command. This modifies the local settings of the current window.

domterm settings style.dark=yes

Settings values

How the raw characters of a settings value is interpreted depends on the keyword: Each keyword expects the value to have a specific type and hence syntax. The raw value is the characters in the settings file or command-file; the actual value is how those characters are interpreted (parsed).

Some settings specify a list of values. In that case the values are seperated by newlines or (unquoted) semi-colons.

Boolean values

For a boolean value any one of true, yes, or on enable the preference; one of false, no, or off disable the preference.

Command values

A command is one or more arguments separate by spaces. Special characters (including spaces) can be protected in single quotes (apostropes) or double quotes, as in typical shells. Escape sequences starting with backslash (see below) are processed within double quotes and outside quotes. (They are currently also processed within single quotes, but that may change.)

Commands that display a session should include the pattern %U for URL that is filled in by the server. If the command does not contain a %U, it is added at the end.

String values

If the type of value is a string, the actual value is roughly the characters of the raw value with any non-nested quotoes removed. “Extra spaces” (more than one in a row, or at the start or end) that are not quoted are also removed. Both single quotes (apostrophes) and double quotes are handled. Thus the following are all equivalent:

history-storage-key=input history
history-storage-key=    input   history
history-storage-key="input history"
history-storage-key='input history'

Escape sequences starting with backslash (see below) are processed within double quotes and outside quotes. (They are currently also processed within single quotes, but that may change.)

Parsing as a string is the same as parsing as a command and then joining all the arguments separated by a single space.

String escapes

\a

Alert (Bell) (Unicode 0x07).

\b

Backspace (Unicode 0x08).

\e

Escape (Unicode 0x1B).

\f

Formfeed (Unicode 0x0c)

\n

Newline (Unicode 0x0A).

\r

Carriage return (Unicode 0x0D).

\t

Tab (Unicode 0x09).

\uHHHH

Unicode 0xHHHH where HHHH are 4 hex digits.

\u{HHHHHH}

Unicode 0xHHHHHH where HHHHHH are 1-6 hex digits.

\v

Veritcal tab (Unicode 0x0B).

\"

\\

\/

The character following the backslash: Quotation Mark (Unicode 0x22), Backslash (Reverse solidus - Unicode 0xC), or plain slash (Unicode 0x2F - pointless but included for JSON compatibiity).

This is a superset of JSON.

Conditional values

A conditional value is one whose value depends on context of how the value is used. Specifically, it is a list of values (separated by newline or semi-colon), where each value is prefixed with zero or more conditions in {...} braces. All of the conditions must be satisfied for the following value to be selected. A condition is one or simple simple conditions, optionally negated (by being prefixed by ‘!’), separated by vertical bars ‘|’. For example the condition {A|!B|C|!D} is true if either of the simple conditions A or C is true, or if B or D is false.

The syntax and meaning of a simple condition depends on the keyword. For example, the command.ssh keyword accepts simple conditions of the form @hostname or user@hostname, as shown in this example:

command.ssh =
 | {@gnu.org}ssh -E /tmp/gnu-ssh.log
 | ssh -E /tmp/ssh.log

This runs ssh with the -E /tmp/gnu-ssh.log when connecting remotely to gnu.org, but with the flag -E /tmp/ssh.log when connecting to other hosts.

Available settings

shell.default = command

Specify a default “shell” command to execute when creating a new terminal. The command can include arguments, separated by spaces. You can uses quotes, as in a shell.

The default is the value of the SHELL environment variable; if that is not set the default is /bin/bash.

frontend.default = application-list

The browser-like program used to create new top-level windows, unless overridden by a specific window-specifier command.

The application-list is a list of command front-end, separated by newlines or semi-colons. The commands are tried left-to-right, until one is found that exists and is executable. The default is currently:

frontend.default = electron;qt;chrome;firefox;browser

The commands electron, qt, chrome, firefox, or browser are equivalent to the corresponding windows-specifier --electron and so on. Otherwise a command may be include command-line arguments (possibly quoted), optionally including %U, similar to the program in a --browser=program option.

command.firefox = command

command.chrome = command

command.electron = command

Command to use for respectively --firefox, --chrome, or --electron.

The default for these is to search in the PATH, possibly with some platform-depending knowledge of default locations.

command.headless = command

Command used when the --headless option requests an “invisible” headless window.

window.geometry = geometry

Control the size and/or of new top-level windows using the syntax of a geometry specifier.

The default is 800x600.

Display styling

style.user = css-style-rules

Set the user stylesheet to the rules in css-style-rules. The latter is typically a multi-line value.

See the Styling section for examples.

style.qt = css-style-rules

qtdomterm only: Set styling for QT user interface widgets. For example to specify the color green for text in QMenu do:

style.qt =
 |QMenu { color: green; }

See more examples.

style.dark = value

This option (if set) selects “reverse video”, which is a color preference for a darker background and a ligher foreground (text). The default is auto, which follows the system/desktop preference if possible, or otherwise off, which selects lighter background and a darker foreground colors. Currently auto is only known to work on Firefox running on Gnome.

style.caret = value

Change the style of the caret (text input cursor). See caret styling.

Key and mouse handling

open.file.application = application-list

open.link.application = application-list

List of applications to try when clicking on a link. If the link’s href is a file: URL, then the open.file.application list is tried first; then the open.link.application list is tried. For a non-file: URL, only the open.link.application list is tried.

For details, see link-handlers.

keymap.master = keymap-overrides

Add or replace keybindings that are active in all modes. See Keyboard shortcuts for defaults and an example.

keymap.line-edit = keymap-overrides

Add or replace keybindings for input line editing.

Remote connnections

command.remote-domterm = conditional-command

When connecting to a remote server over ssh, the command that runs domterm on the server. The default is domterm, but you may need to use this option if domterm is not in the remote PATH or you want to pass extra options (perhaps for debugging or logging) to domterm. The value is conditional, where the simple conditions have the form of either @hostname or user@hostname. For example:

command.remote-domterm =
 | {@192.168.1.55}/home/bothner/DT/bin/domterm
 | {jones@mac.example.com}/Users/jones/bin/domterm -d 15

The user and hostname are matched literally against those used to connect remotelty. If user is specified it must match exactly, otherwise any (or no) user matches.

command.ssh = conditional-command

The command to use instead of ssh to connect to a remote server. The value is a list of alternative commands, optionally prefixed by conditions, in the same way as for command.remote-domterm.

predicted-input-timeout = timeout

When the user types a “simple” keyboard action (a printable character, left/right arrow key, backspace, or delete) the keystroke will be sent from DomTerm to the user application which will then update the display (“echo”) in the “standard” way. However, there is a delay caused by the round trip from browser to application and back which may be noticable, especially if browser and application are separated by a network. To hide this delay, DomTerm will guess that the keystroke will have the “standard” effect, and tentatively update the display before it gets the confirming echo. DomTerm will undo the predicted update unless it received a confirming echo within timeout seconds. The default timeout is 0.4 seconds.

The following settings are used to timeout if a connection fails. All these values are in seconds; no timeout happens if the values are zero.

remote-input-interval = input-interval

If non-zero, the local browser sends input data at least as frequently as every input-interval seconds. If there is no keyboard or other event, artificial data is sent. Defaults to 10 seconds,

remote-input-timeout = input-timeout

If the remote (application) end has not received any input data in input-timeout seconds and input-timeout is non-zero, it assume the connection has failed. Defaults to twice remote_input_interval.

remote-output-interval = output-interval

If non-zero, the remote (application) ends some data to the local browser at least every remote_output_interval seconds. Defaults to 10 seconds.

remote-output-timeout = output-timeout

If the local browser end of the connection has not received any output from the remote application end in remote_output_timeout seconds (and it is non-zero), it assume the connection has failed. (This timeout is both in the browser front-end, and in the domterm server on the local end of the ssh connection.) Defaults to twice remote_output_interval.

Debugging and logging

log.file = specifier

Send logging output (as controlled by the -d and --verbose flags) to the specified file. The specifier can be one of these special values: stderr writes log entries to standard error, with timestamps and colors; stderr-notimestamp (or notimestamp) is the same as stderr without timestamps; stdout writes to standard output, with timestamps and no colors. Otherwise, specifier is printf-style format string that is used for a file that is appended to: %P is replaced by Process ID of the domterm process; %% is a literal percent symbol.

The default is /tmp/domterm-%P.log.

log.js-verbosity = level

Write more information to the JavaScript console.

log.js-to-server = setting

Send diagnostic/logging messages in the browser (normally written to the JavaScript console as controlled by by log.js-verbosity) where it is written using lwsl_notice to the location specified by log.file.

Sets the -d option to 5 if not specified; if specified the -d mask must have 4 set in the mask. (If you divide mask by 4, the result must be an odd integer.)

log.js-string-max = length

If positive, maximum length of strings to string to the JavaScript console.

debug.input.extra-delay = delay

Delay an extra delay seconds before sending keyboard and other events from client (browser) to server (application). Especially useful for testing predicted-input-timeout, which should be higher than debug.input.extra-delay.

Miscellaneous settings

history.storage-key = string

A string (default "DomTerm.history" used as an identifier for the JavaScripr storage mechanism to preserve line-editing history.

history.storage-max = number

Maximum number of entries (default 200) of line-editing history to preserve,

password-hide-char = string

Character used to hide characters in password fields. The default is "\u25CF" “black circle”. To change it to “bullet” you can do:

domterm settings password-hide-char="\u2022"

password-show-char-timeout = number

Number of seconds (default 0.8) to show the actual password character before it is replaced by the password-hide-char.

terminal.minimum-width = width

Mininum logical width (default 5, in columns/characters) of a terminal: If the available width is less, use this width for line-wrapping etc. (This avoids certain pathological behavior.)