T8wn

Writing a client

8TML > Guides

A client reads 8TML pages and shows them: a browser on an 8-bit machine, a viewer on a PC, or a converter. This guide is a map of what a client does. The binding details are in the Reference.

Reading a page in one pass

8TML is designed so that a client never needs the whole page in memory to understand it:

  • Is it a page? A response is an 8TML page exactly when its first line is --- and the first key in that block is 8tml. Anything else is shown as plain text.
  • Lines decide blocks. After the header, the start of each line says what it is: heading, list item, quote, fence, field and so on. One line of lookahead is never needed.
  • Inline markup is a small state machine: the current color, three flags (b, i, rev) and a few short buffers: link text up to 80 characters, a URL up to 255, a tag name and an entity.
  • Unknown things are ignored, never fatal: unknown header and stylesheet keys, unknown block types (skipped up to the closing :::), unknown tags (printed as text).

Layout

  • Wrap paragraphs at spaces to your screen width; break a word only when it is longer than a whole line. List items wrap with a hanging indent.
  • Map each color name to the nearest color you have; without colors, ignore them.
  • Show characters your machine lacks as the nearest equivalent (see Files and characters).
  • Reset everything a previous page set at the start of each page: colors, case and inline state.

Styles

Resolve the cascade once per page: your defaults, /site.8ss of the host (fetched once per site and cached, a missing one remembered), the page’s own stylesheet, the header keys. Keys with your machine’s prefix override plain keys within the same source.

Network

  • HTTP/1.0 GET, and POST for forms, with a Host: header.
  • Follow 301, 302, 303 and 307 up to five times in a row; 303 becomes GET.
  • Check Content-Type before reading the body: refuse text/html, image/*, audio/*, video/* and font/*, read everything else.
  • https:// addresses go through an HTTPS proxy if the reader has set one up.
  • Ignore links with schemes other than http and https.

Forms

  • Links and form fields share one focus order, in page order.
  • Support at least 16 fields per form, 80 characters per text field and 255 per text area.
  • Mask passwords, never store them in history, bookmarks or caches, and clear them when the page is left.
  • Never send a POST again by itself.

Limits

Use the memory you have. When a page doesn’t fit, show what fits and tell the reader that the page was cut. You may refuse anything above your limits, but never crash or hang, whatever the input. See Client limits.

Existing clients

VVV, a browser for the Commodore 64, is one client, written alongside the specification. A reference implementation for the PC checks pages and previews them the way a 40-, 32- or 22-column client shows them; the previews on these pages come from it.

Contents