The page (device 7)

The page shows typeset prose in a rectangle of the screen: proportional fonts, shaped, bidirectional and wrapped, with figures and tables between the paragraphs. The program hands the device a document, a binary list of styled text much like a display list; the host lays it out with its fonts and draws the part in view. The device parses no markup. It is slot 7, version 0: an image gets it by listing it in its header (terse pack --device 7:0). Without it, and for the unknown functions 706h..7FFh, a call returns FFFF_FFFFh.

Layout differs between hosts, because fonts differ. A program learns only two facts about it, both as input events: the document's height and, when it asks, where an anchor is. So a recorded run replays exactly whatever the fonts.

Rectangle and scrolling

The page is drawn inside its rectangle (x, y, width, height in screen units) and nothing of it outside, above the terminal's cell backgrounds and below the vector shapes and terminal characters. The document is one column as wide as the rectangle. The scroll value is the distance from the top of the document to the top of the rectangle. A width or height of 0 hides the page.

Calls

a7CallArgumentsResult
700hsubmita0 = document, a1 = length0 done, 1 rejected
701hclearnone0
702hregiona0 x, a1 y, a2 width, a3 height0
703hscrolla0 = y0
704hbackgrounda0 = colour0
705hlocatea0 = anchor id0 done, 1 rejected

After reset: no document, rectangle (0, 0, 0, 0), scroll value 0, background FF00_0000h (opaque black).

The document

A document is 1 to 65,536 bytes of commands, each an opcode byte and its operands, little-endian. It ends at End, at the end of the bytes, at an unknown opcode, at a command whose operands are cut off, or at a Table command whose column count is 0 or above 8. The commands before that are used.

OpCommandOperandsEffect
00hEndnoneEnds the document
01hTextn (2 bytes), n bytes of UTF-8Adds text to the current paragraph or cell in the current style
02hFontface (0 sans, 1 serif, 2 mono), flags (bit 0 bold, bit 1 italic)Font for later text; an unknown face is 0
03hSizesize (1 byte)Font size in screen units, clamped to 6..96
04hColourr, g, bText colour
05hParagraphalign, indent, space, flags (1 byte each)Starts a paragraph
06hRulenoneA paragraph that is a horizontal line
07hAnchorid (2 bytes)Later text and figures belong to id; 0 is none
08hFigurewidth (2), height (2), align (1), n (2), n bytes of path commandsA figure block, see figures on the page
09hTablecolumns (1, 1..8), flags (bit 0 header), one align byte per columnStarts a table block
0AhCellnoneStarts the table's next cell
0BhEnd tablenoneEnds the table

Align is 0 start, 1 centre, 2 end, anything else 0. Other flag bits are ignored.

At the start of a document: sans, no flags, size 14, colour (229, 229, 229), anchor 0, and an implicit first paragraph: start-aligned, indent 0, space 0, wrapping. Font, size, colour and anchor carry on across paragraphs, tables and figures.

Text

Each Text command is decoded on its own: malformed UTF-8 becomes U+FFFD as on the terminal (so a sequence split across two Text commands is malformed in both), but code points above U+FFFF are kept. U+000A breaks the line; U+0009 is a space; other control characters (U+0000..U+001F, U+007F..U+009F) are ignored. Consecutive spaces are kept.

Paragraphs and rules

Tables

A Table command ends the current paragraph and starts a block with the space of the latest Paragraph command above it; if the current paragraph has no text yet, the table takes its place and its space. Each Cell command starts the next cell in row order, rows of columns cells; missing cells of the last row are empty. Text before the first Cell is ignored. Text adds to the current cell (U+000A breaks a line in it); Font, Size, Colour and Anchor work as anywhere.

A table ends at End table, and also at a Paragraph, Rule, Figure or Table command (which then does what it does) and at the end of the document. A table with no cells takes its space and nothing else. The colour at the Table command is the colour of its rules. With flag bit 0 the first row is a header: drawn bold whatever the font's flag, with a rule under it. Cell or End table outside a table does nothing.

Limits: 1,024 cells per table and 4,096 per document. A Cell that would pass either limit, and the text after it up to the end of its table, are ignored (Font, Size, Colour and Anchor still change the state).

Layout, in screen units:

A line of a cell counts as a line for presses and locate; a row's lines are taken left to right.

Layout and presentation

The host chooses fonts for the three faces and does shaping, the bidirectional algorithm within each line, Unicode line breaking and font fallback. It draws the background, then what is in view, clipped to the rectangle. How text looks cannot be observed. Layout happens outside the machine's frames, is never charged and may take the host several frames (it shows the previous layout or nothing meanwhile); the machine never waits.

Events

TypeNameabc
08hPage laid outheight bits 0..78..1516..23
09hPage anchorid lowid highbits 3..5 buttons
0DhPage locatedid lowid highline height
0EhPage located yy bits 0..78..1516..23

A height event describes an earlier frame's document and width; after a newer submit another follows. Use it for clamping and progress, never for anything that must be exact.

Reference layout

A host without fonts, such as terse run, uses this pure function of document and width, a stand-in for tests.

State and charges

State (for the hash and snapshots): a present flag, the clamped rectangle (four 2-byte values), the stored scroll value (4), the background (4), the document's length (4, 0 for none) and its bytes. Layout and pending locates are not state.

Each call costs 4 units; an accepted submit 1 more per 4 bytes, rounded up. Layout is free.

Example

A heading, a paragraph with an anchored word and a table. The library has no builder for the table commands, so op appends their bytes: 09h, 2 columns, flags 1 (header), aligns start and end; 0Ah before each cell; 0Bh.

#include "terse.h"
#define T(s) doc_text(s, sizeof(s) - 1)
static uint8_t doc[1024];
static void op(const uint8_t *p, uint32_t n) {
    if (doc_ptr + n <= doc_limit)
        while (n--) *doc_ptr++ = *p++;
}
static const uint8_t table[] = {9, 2, 1, DOC_START, DOC_END};
static const uint8_t cell = 0x0A, endt = 0x0B;
int main(void) {
    terse_event e;
    doc_begin(doc, sizeof doc);
    doc_size(21); doc_font(DOC_SANS, DOC_BOLD); T("Hello");
    doc_size(15); doc_font(DOC_SANS, 0);
    doc_paragraph(DOC_START, 0, 10, 0); T("Press ");
    doc_anchor(1); doc_colour(120, 170, 255); T("here");
    doc_anchor(0); doc_colour(229, 229, 229); T(" to quit.");
    op(table, 5);
    op(&cell, 1); T("Key");  op(&cell, 1); T("Does");
    op(&cell, 1); T("Esc");  op(&cell, 1); T("nothing");
    op(&endt, 1);
    doc_end();
    page_region(64, 0, 512, 480);
    page_submit_doc(doc);
    for (;;) {
        while (terse_event_pop(&e) != EV_NONE)
            if (e.type==EV_PAGE_ANCHOR && EV_ANCHOR_ID(e)==1)
                return 0;
        terse_wait_frame();
    }
}

The program never learns where "here" was drawn; a press on it arrives as event 09h with anchor 1.