# TERMINAL — text configuration instead of a patched binary

TINST installs terminal escape sequences by writing them into `TURBO.COM`.
This port does the same job with a **text file**, `TP3.TRM`, that `tpshell`
reads at startup. The shell never modifies itself; the file can be edited,
copied, versioned or generated, and a bad file is a data error rather than a
corrupted executable.

## The file

Plain text, one `KEY=value` per line. `;` at the start of a line is a comment.
Blanks around the key and value are ignored; the key is case-insensitive.
Unknown keys are ignored (so files can carry fields another tool needs).

```
; TP3.TRM
NAME=ANSI
CLEAR=\e[2J\e[H
HOME=\e[H
GOTO=\e[%r;%cH
NORMAL=\e[0m
MARKED=\e[1;7m
BEEP=^G
```

| key | meaning |
|---|---|
| `NAME` | a label, not interpreted |
| `CLEAR` | clear the screen (and usually home the cursor) |
| `HOME` | home the cursor |
| `GOTO` | cursor addressing, with the placeholders below |
| `NORMAL` | normal text attribute |
| `MARKED` | highlighted attribute (the shell's command letters) |
| `BEEP` | the bell |

### Values

Values are **decoded**, so the file stays readable:

| written | byte |
|---|---|
| `\e` or `\E` | ESC (27) |
| `\r` | CR (13) |
| `\n` | LF (10) |
| `\t` | TAB (9) |
| `\\` | a backslash |
| `^X` | control-X (X uppercased, minus 64): `^G` = BEL (7) |
| anything else | itself |

`GOTO` placeholders:

| placeholder | output |
|---|---|
| `%r` | the row in decimal (1-based) |
| `%c` | the column in decimal (1-based) |
| `%R` | one byte, `row + 31` (VT52-style) |
| `%C` | one byte, `col + 31` |
| `%%` | a literal `%` |

A missing `TP3.TRM` means the built-in ANSI defaults (the sequences the shell
had before there was a config). A malformed line leaves the defaults (and
anything read before it) in place; it never silently half-configure the screen.

## The editor's keys: `TP3.KEY`

The same design extends to the editor's command keys. `Editor.Run` reads
`TP3.KEY` (or keeps the built-in defaults) and the main command dispatch uses
the loaded map instead of compiled-in constants.

```
; TP3.KEY
QUIT=^Q
CANCEL=^U
PREFIX=^K
LITERAL=^P
WORDLEFT=^A
CHARLEFT=^S
CHARRIGHT=^D
WORDRIGHT=^F
LINEUP=^E
LINEDOWN=^X
SCROLLUP=^W
SCROLLDOWN=^Z
PAGEUP=^R
PAGEDOWN=^C
INSERTTOGGLE=^V
DELETECHAR=^G
DELETELEFT=^H
DELETEWORD=^T
INSERTBREAK=^N
DELETELINE=^Y
REPEAT=^L
AUTOTAB=^I
NEWLINE=^M
```

Values decode exactly like `TP3.TRM` values and must be **one byte**; a value
that is not one byte makes the load report not-ok (the defaults stand).
Unknown names are ignored. `Del` and `^J` remain aliases of `DELETELEFT` and
`NEWLINE` and are not configurable in this slice.

`tests/term_config.sh` asserts both the escape loader and the key loader byte
for byte (`term_ansi`, `term_vt52`, `key_default`, `key_custom`).

### Not in this slice

TINST also remaps the **Ctrl-K sub-commands** and the **Esc/ANSI cursor
sequences** (`HandleEsc`). Those are two further tables in `Editor.mod`; the
same `Keys` pattern extends to them, as a separate step. The single-key command
map above is the bulk of them and is what this slice covers.

## `tp3cfg`

The configurator - TINST's role, without the patch. It lists the terminals it
knows, asks for one, and writes `TP3.TRM`.

```
cd shell
./tp3cfg            # list, choose, write TP3.TRM
```

A terminal is added by one `Build` case in `Tp3Cfg.mod` and one bump of
`NumTerms`; the sequences are written in the same readable spelling as the
file. `tp3cfg` is built by `make` alongside `tpshell`.

Current table: **ANSI**, **VT100** (ANSI-compatible for what the shell emits),
**VT52** (raw-byte cursor addressing, `%R`/`%C`).

## Extracting TINST's full terminal table (next measurement)

`TINST.COM` embeds its table; `TINST.MSG` is only its UI text, and the
disassembly in `Resources/turbopascal3source` is `TURBO`, not `TINST`. The
method that measures rather than guesses:

1. Run the original `TINST` in dosemu once per terminal, selecting each entry
   from its menu.
2. Save the patched `TURBO.COM` each time and diff it against the untouched
   copy. TINST patches known offsets, so every terminal's exact escape strings
   fall out at the offsets TINST itself uses.
3. Convert each diff into a `tp3cfg` `Build` case.

That is deliberately not done by transcription: the sequences are what the
original writes, and the diff is the evidence. Until it is done, the table
above is the curated subset the shell needs.

## Not in this step: the Ctrl-K and Esc sub-tables

The editor's **Ctrl-K sub-commands** and its **Esc/ANSI cursor sequences**
(`KCommand`, `HandleEsc`) are still hard-coded.  The single-key command map is
configurable now; those two tables are the remaining part of TINST's editor
configuration, and `Keys` is the pattern to extend.