ADR-0118: A buffer's language can be picked by hand

Status: Accepted
Date: 2026-09-16
Deciders: jka
Decision: D112

Context

A buffer's highlighter came from its file name alone (ADR-0032, ADR-0046): the exact file name, then the extension, then the name with its last suffix removed. rio never looks at the content, so there is no shebang or modeline detection. Two cases had no remedy. Code pasted into an untitled buffer was always plain text, and a file whose name suggests the wrong language was always highlighted wrongly.

The list of languages is not fixed. Every installed syntax extension (ADR-0039) adds one, so any control that lists them is data-driven and unbounded. ADR-0092 retired the last menu of that shape.

Decision

View ▸ Language… opens the shared bounded picker (ADR-0092) next to Theme…. Its rows are Auto-detect, labelled with what the file name would give, then Plain Text, then every language the registry knows, shipped or installed. The list is built when the picker opens, and the picker starts on the buffer's current choice.

The choice belongs to the buffer, not to the editor group or the file type:

It is GUI view state, held with the buffer like its modified flag (ADR-0022). The core is not involved, and the choice follows the buffer when it moves to another group.
It has three forms: detect by file name (the default), no highlighting, or a named language.
It persists through Save As and renames until the user picks Auto-detect again. A hand-picked language is a statement about the content, and a new name does not withdraw it.
It is not saved in the session. A session restores file paths only and does not restore untitled buffers at all, so after a restart detection by name applies again.
If the named language disappears, for example because its syntax extension was removed, the buffer falls back to detection by name without an error.

A buffer is re-highlighted whenever its path changes, whether by Save As or a rename, so an untitled buffer saved as foo.tcl is highlighted as Tcl at once.

Alternatives considered

A View ▸ Language submenu, which was the original proposal. The cascade would grow with every installed syntax extension, and over-tall Tk menus misbehave on X11. ADR-0092 replaced the theme cascade with a picker for exactly that reason.

Detecting the language from content, such as a shebang line. It would help extension-less scripts, but it is a separate question from a manual override and was left out of this step. A hand pick covers pasted code, which content sniffing would only guess at.

Remembering the choice across restarts. Sessions store paths, not per-buffer view state, and the main case (an untitled buffer) is not restored anyway. Detecting by name again after a restart is the least surprising behaviour.

Consequences

Pasted code and misnamed files can be highlighted correctly without renaming anything.
The syntax registry has to answer two questions besides "which scanner fits this path": the names of all registered languages, and the scanner for a given name.
A hand pick outlives a rename, so a user who renames notes.txt to notes.tcl after picking Plain Text keeps plain text until they choose Auto-detect.
A choice lasts only for the running session. If users want it kept, a per-file override would need a home in the session data.
Shebang detection remains open, as ADR-0046 already noted.