Using the shell and the reader

terse-host opens a window and runs a system of machines. The first of them is the shell, a Terse 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 both from the user's side: the keys, the screens, and the prompts the host shows.

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

The shell

The screen has a bar on row 0 and the machines' tiles below it.

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), 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).

KeyIn the launcher
Up, Downmove the cursor
Enterstart the program under the cursor (the new machine gets the keyboard), or give the keyboard to the machine under it
Escgive the keyboard back to the selected machine
Tab or Right, Shift+Tab or Leftselect the next or previous machine
1 to 8select the machine with that handle
Xstop the selected machine
Ppause or resume it
Zzoom it; Z again goes back
Lthe next layout: master and stack, grid, gallery, zoom
Ssave the session
Dwith the cursor on the restore entry (and only there): discard the saved session

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.

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

RequestThe prompt shows
Subscribe, unsubscribethe 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)
Publishwhether it is an article or a document, its title and size
Set profilethe display name, and whether search may find it
Set nicknamethe 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.

The reader

The reader shows every view on the page in the sans face. The terminal's bottom row is its status row: key hints, a position such as 2/3, or the outcome of the last action. Row 28 is used while you type a feed address. The help page (? or F1) lists the keys of every view and shows your own feed address: your key in full, in groups of eight hex digits, then @ and your public relays, or, if none of your relays is public, a note that only people on the same relay will find your feed.

Timeline: the articles of the feeds you follow, newest first, each with its title and a dimmer line with the feed (name and short key), the date and time (UTC), the size, and ↳ reply or not downloaded where they apply. New entries appear without a key press. With no entries, a page says so and which keys to press.

KeyIn the timeline
Up, Down, PgUp, PgDn, Home, End, wheelmove the selection (the wheel 3 entries a step)
Enter, clickopen the article; a document (marked ◆) is passed to the shell
/search
Ffeeds
Mthis manual's index
? or F1help
Tpublish a test article
Escquit

T publishes "Test article N", a few paragraphs: the reader puts the article, publishes it and, if you do not yet follow your own feed, subscribes you to it so that it shows in the timeline. The host asks you first, and the status row says what came of each step. T works in the timeline, feeds and help views.

Feeds (F): the feeds you follow, each with its name and short key (you marks your own, your nickname a name you gave it, @ through a relay its address names one your relays do not hold), the highest entry number and how many entries are held.

KeyIn the feeds view
Up, Down, PgUp, PgDn, Home, End, wheel, clickselect a feed
Enterthe feed's page
Ssubscribe: type or paste a feed key or address (key@relay, or a terse:feed/ link) on row 28 (spaces and line breaks are ignored), Enter subscribes, Esc cancels, Backspace deletes
Uunsubscribe from the selected feed
Na nickname for the selected feed, which only you see; empty removes it
Pyour public name, then Y or N: whether search may find it
/, T, ? or F1as in the timeline
Esc, Backspace, Leftback to the timeline

Names are checked before they are sent (1 to 48 bytes, no control characters, no space at either end), and the host asks you before either is set. Names are chosen by the feeds themselves and are not unique, so the reader shows the short key beside every name.

Search (/): type words and press Enter. The reader searches two places at once and lists the results under a heading each:

Both match the same way: the words must occur as they are typed, letters A to Z matching a to z, every other character only itself (so "köln" finds "Köln", but "KÖLN" does not). Up, Down, the wheel or a click select; Enter opens a feed's page or an article; Esc goes back.

Feed page (Enter on a feed, or a terse:feed/ link): the feed's name (and whether it is your nickname or its own), its key in full, the relays a link's address names, and whether you follow it. S subscribes (with those relays, which your host contacts only if your relays lack the feed), U unsubscribes, Esc goes back.

Reading an article

The article fills the screen above the status row as a centred column 512 units wide: the title, a grey line (feed key prefix, entry number, date, size), a rule, then the text formatted as Writing an article describes. The status row shows how far you have scrolled, from 0% to 100%.

KeyIn an article
Up, Downscroll by 20 units
PgUp, PgDn, Spacescroll by the view less one line
Home, Endthe top, the end
wheel60 units a step
Tab, Shift+Tabthe next or previous link
Enter, clickfollow the current link
Esc, Backspace, Leftback

The current link is amber, its target is on the status row and the page scrolls just enough to show it. After you scroll, Tab starts again from the first link in view (Shift+Tab from the last). Following a link opens an article (terse: and a blob ID) or a feed's page (terse:feed/); a link to a program, a program image or a document is passed to the shell, as described above. Articles have no links to web pages: an address such as http://example.org is ordinary text. Esc goes back through the articles you followed, up to 8, each at the place it was scrolled to, then to where you started. The reader shows at most 48 KiB of an article: one opened from the timeline that is longer ends with a note saying how much is shown; one opened by a link that is longer is not shown, and a page says so, as it does for an article that is missing or cannot be fetched.

The reader also gets the first 8 article links of an article as you open it, so they open at once when you follow them.

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.