# xterm

The terminal as a module (novox/hq ADR 0208, research 026, to-be 42 phase 2, step 5).

- **Claims `node-terminal-emulator`** and serves its verb `open`.
- **Requires `x11-display`.** In a Wayland session, `xwayland` would provide it.
- **Package `xterm`.**
- **Environment** (ADR 0203): `TERMINAL=xterm`. i3's `$mod+Return` runs `i3-sensible-terminal`, which
  starts whatever `$TERMINAL` names, so the window manager no longer names the terminal.
- **X resources**, contributed to the `xresources` slot `normal` and placed by `xorg` in its resources
  file. It owns no file of its own.

## The resources

They are those both workstations ran, with three changes:

- **face:** `JetBrainsMono Nerd Font` 12, replacing Hack (research 026/04);
- **scope:** every resource is under `XTerm*`. Today they were `*faceName`, `*background` and so on,
  which reached every Xt program. `XTerm*` also outranks a `*name` resource of yours, so the old
  `~/.Xresources.d/xterm` cannot win over them while it is still merged;
- **scrollback:** `saveLines` 10000 instead of 2000.

The palette (background, foreground and the sixteen colours) is today's, unchanged. So are the
clipboard keys: Ctrl+Shift+C copies to the clipboard and Ctrl+Shift+V pastes from it.

Every one of these values is a **config value** (ADR 0348; issue 1656) with today's value as its default:
`face`, `size` (the predefined `font-size`, 6 to 72), `save-lines`, `term-name`, `render-font`, `bold-mode`,
`always-bold-mode`, `allow-bold-fonts`, `background`, `foreground`, `color0` to `color15` (each `#rrggbb`),
and the two clipboard bindings `copy-binding` and `paste-binding`. `files/xresources-normal` holds only
`${config:<key>}` placeholders, so a machine changes its font size through mesh-config. The manifest test holds
the file to the keys, and the file filled with the defaults to the text every machine had before.
The tools keep no copy of the values: `xterm_font` and `xterm_colours` read the `XTerm*` lines of the rendered
resources file `xorg` writes (`~/.config/xorg/xresources`) as the module's value, and say so when it is not there.

## Tools

| tool | | what |
|---|---|---|
| `node-terminal-emulator.open` | d | a terminal in the session: the login shell, or a command run through it (`$SHELL -lc`), in a directory (the home by default), with an optional title, and `hold` to keep it open. It starts as a transient unit of the account's service manager (`systemd-run --user`), so it outlives the call and every runtime restart |
| `xterm_font` | r/a | the face and size in force beside the module's value (from the rendered resources), and the installed font they resolve to (`fc-match`); set face or size for terminals opened from now on. Only installed faces are accepted |
| `xterm_colours` | r | background, foreground, cursor and the sixteen colours as `#rrggbb`, each beside the module's value from the rendered resources |

## What it leaves found

`~/.Xresources.d/xterm`, and the `#include` of it in `~/.Xresources`.

## The one-off migration

**Delete `~/.Xresources.d/xterm` and its `#include` line in `~/.Xresources`** once `xterm` is
assigned (see `xorg`'s README for the rest of that file). Until then they are merged after the
mesh's. Being `*`-scoped, they lose to this module's `XTerm*` values, and still reach every other Xt
program.

## What changes when it is assigned

| | g14 | shanks |
|---|---|---|
| package | none (`xterm` present) | the same |
| `xorg`'s resources file | gains this module's resources | the same |
| environment | gains `TERMINAL=xterm` | the same |
| running terminals | **nothing**. The resources are merged at the next login | the same |
| next login | new terminals in JetBrains Mono, with 10000 lines of scrollback | the same. The desktop has a hand-copied build of the face until `fonts` installs the package |

## Blockers

None. It needs `xorg` assigned for `x11-display`, and `fonts` for the face. Without `fonts`,
fontconfig picks the nearest installed face, and `xterm_font` says which one in `resolves_to`.