Using the shell
terse-host opens a window and runs a system of machines. The first of them is the shell, a Terse32 program like any other, which starts the others and shows them as tiles; one of the programs it offers is the reader, where you follow feeds and read articles such as this one. This article describes the shell from the user's side: the keys, the screens, and the prompts the host shows; Using the reader does the same for the reader.
Starting
cargo run --release -p terse-host -- --demo
builds everything, sets up four sample articles and opens the shell. The first time, it creates your feed key (~/.config/terse/identity.key), subscribes you to your own feed and publishes the samples to it; run again, it publishes nothing new. After that, cargo run --release -p terse-host with no image named opens the shell.
Without --relay the host uses the relays listed in relays in the config directory (terse relay add <url> writes it), else a relay already listening on ws://127.0.0.1:7878, else one it starts itself on that port. --relay may be given several times; --relay none runs without a network. To share with someone, one of you runs a relay the other can reach, the other adds it with terse relay add ws://their-host:7878, and you exchange feed addresses (the key, @ and a relay others can reach: the reader's help page and terse feed address show yours). How relays work is in The network.
The 3D drawings, the gallery's included, are seen from an eye that follows the pointer; --parallax off keeps it still. --renderer software draws with the CPU instead of the GPU, and with it --panels flat draws the gallery's panels upright instead of in perspective (perspective or auto, the default; the GPU always draws them in perspective). Programs in the phosphor style (every program, with --force-phosphor) are drawn on a colour vector monitor; --tube p31, amber or vectrex gives a green, amber or white tube instead (xy is the default), --vignette darkens its corners and --no-trails turns the afterglow off.
The shell
The screen has a bar on row 0 and the machines' tiles below it.
- The bar starts with the home segment
⌂, then one segment per machine: its handle, a mark (…loading,‖paused,■exited,!faulted,✗failed,⊘halted), its title and its share of the frame budget in its last frame (for a halted machine, the wordhaltedinstead). The machine with the keyboard is blue, the one selected in the launcher amber; the clock (UTC) is at the right. A click on a segment gives that machine the keyboard (in the gallery it turns the ring to it instead); a click on⌂opens the launcher. - Each tile shows a machine's whole screen, scaled, with a blue frame round the one with the keyboard. Layouts: master and stack (the first machine on the left half, the others stacked on the right; the default), grid, the gallery (below), and zoom (one machine over the whole area, the others hidden but still running).
- The gallery: every machine's screen is a panel standing on a ring in 3D, in a wireframe monitor case on a stand over a faint ground grid. The selected machine is at the front, on the glass; the others are turned half way towards you. Selecting a machine in the launcher (Left, Right, Tab, Shift+Tab, 1 to 8) turns the ring over 20 frames to bring it to the front; in the gallery a click on a machine's bar segment turns the ring to it (back in the launcher if a machine had the keyboard). Giving a machine the keyboard (Enter, Esc, a click on its panel, starting a program, which joins the ring) flies the whole scene over 20 frames until its panel lies flat over the area below the bar, then shows it there as in zoom; F12 flies it back to the ring. With the launcher open the ring stands to its right. The panels move with the eye (parallax) like any 3D drawing; while the scene flies, clicks reach no machine.
- A click on a machine's picture or panel gives it the keyboard; the click also reaches the machine. A machine that exits or faults keeps its tile and last picture (a fault is shown on its bottom row) until you stop it; the keyboard then goes back to the shell.
F12 is the home key: wherever the keyboard is, it brings you back to the launcher, and no program ever sees it. The launcher is shown while the shell has the keyboard (at start, and after F12), with the tiles moved to its right. It lists "Manual" (Enter opens the reader on this manual's index), the built-in programs by title (reader, sparks, fetch, hello, sketch, holo, reports), then "From your feeds": the current version of each program of the feeds you follow, with its publisher's name and short key, marked ↓ while its image is not yet downloaded. Then come the machines with their state (a faulted one with the fault kind and pc, a failed one with the reason: not found, not a valid image, needs a device this host does not have, no room; a halted one, below), and, under the heading SAVED BY TERSENET, the states Tersenet saved of slow machines.
| Key | In the launcher |
|---|---|
| Up, Down | move the cursor |
| Enter | start the program under the cursor (the new machine gets the keyboard), or give the keyboard to the machine under it |
| Esc | give the keyboard back to the selected machine |
| Tab or Right, Shift+Tab or Left | select the next or previous machine |
| 1 to 8 | select the machine with that handle |
| X | stop the selected machine |
| P | pause or resume it |
| Z | zoom it; Z again goes back |
| L | the next layout: master and stack, grid, gallery, zoom |
| S | save the session |
| D | on the restore entry: discard the saved session; on a state saved by Tersenet: delete it |
A click on a program starts it; a click on a machine selects it and gives it the keyboard. Programs are started by their identity, built-ins too, so their named records follow them from version to version. The layout chosen with L and Z is kept for the next run.
holo shows the 3D vector display: 1 to 6 (or Space) choose a scene, the arrows turn the model, P switches to the phosphor style, H makes the wireframes solid. Scene 6, the cockpit, looks out of a small craft through its canopy; its three consoles show parts of holo's own terminal (instruments, a log, a list of targets) on Surfaces, and a click on a row of the list on its tilted console selects it. The arrows bank and pitch the craft; the status line stays on the glass.
Sessions
S saves the session: every running or paused machine as a snapshot of its whole state, and the layout, the selected machine and how many there are. The bar says "Session saved" or "Could not save the session". When the shell starts and a session was saved, the launcher's first entry is "Restore last session (N programs)": Enter restores the machines in their order, where they were (a game mid-play, the reader on its article at the same place), with the layout and the keyboard on the machine that was selected. D, with the cursor on that entry, discards the session. A machine that cannot be restored (its image is gone from the store and no relay has it, or the snapshot is unreadable) shows why, as a failed start does. A snapshot holds one exact version of a program; named records are not in it. Nothing is saved without S. The snapshot format is in The state hash.
Halted machines
A program runs on devices, and on a slow computer a device can keep making frames late. Tersenet then steps in, for every machine that uses that device. First it warns: it saves each such machine's state, and the machine keeps running; its line in the launcher says "A device it uses was slow; Tersenet saved its state." If the device goes on making frames late, Tersenet saves them again and stops them: they are halted. The bar says so once, for example "Tersenet stopped sparks: device 3 was too slow (state saved)"; the machine's tile shows why in words instead of its last picture; and its line in the launcher says "Tersenet stopped it: ... kept making frames late. Its state was saved: Enter restores it." Enter restores it, in the same tile.
Every state saved this way is listed in the launcher under SAVED BY TERSENET: Enter restores one, D deletes it. There is one place per machine, so a new warning replaces the last save. How slowness is measured and reported is in Performance reports.
Open requests
A machine may ask the shell to open a program (by its identity) or a blob (by its ID); the reader does this when you follow a link to a program, an image or a document. The shell takes these requests only from the machine with the keyboard, one at a time, at most one a second from each machine, and ignores a machine's requests for ten seconds after you say no.
- A built-in program starts at once in a new tile.
- Any other program is fetched first (the host looks it up on its relays if it holds no entry for it); then the bar asks, for example,
reader asks to start Tool by Alice 3fa9c2…c21e07. Y/N. The keyboard goes to the shell until you answer: Y starts it in a new tile with the keyboard, N or Esc does not. - For a blob, the shell reads its first bytes. An image is asked about as an unpublished program, with its title and short ID. A document starts the program of its format with the document as its argument (a published format is asked about the first time in a run). Anything else opens in a new reader tile.
- A failure (not found, no free handle) is a brief message in the bar.
Consent prompts
A program may ask the host to subscribe to a feed, unsubscribe from one, publish an article or a document in your name, set your public name, or set a nickname. The host then shows its own prompt over the bottom four rows of the window, over every machine's picture. The program can neither see nor draw over it.
| Request | The prompt shows |
|---|---|
| Subscribe, unsubscribe | the feed key, as its first and last six hex digits (3fa9c2…c21e07), and the relays a feed address names (the host may connect to them) |
| Publish | whether it is an article or a document, its title and size |
| Set profile | the display name, and whether search may find it |
| Set nickname | the feed key and the nickname |
Every prompt names the title of the program that asks. Y allows; N or Esc refuses; every other key, Enter included, does nothing. While the prompt is up the keyboard goes to the host, not to any program. Several requests are asked about one at a time. terse-host --consent allow or deny answers every request without asking; ask is the default.
Where to go next
How articles are written: Writing an article. How the shell's devices work: The machines device. Feeds and consent from a program's side: Feeds.