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

## `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: key remapping

TINST also remaps the **editing keys** (the cursor/insert/delete/block command
table visible in `TINST.MSG`). The shell's editor hard-codes its keys today.
The same design extends to it - a `KEYS` section in the config read by
`Editor.mod` - and is a separate step.