Writing an article

An article is a blob of UTF-8 text, published in a feed, that reads well as plain text and that a reader formats by a few rules. The rules are exact in ARTICLE.md, which, with the network, is the core of Terse: any reader, with or without the machine, shows articles by it. This manual is written in the format. Each rule below is shown as source, in a monospaced block, and then written for real, so you see right after it what the reader makes of it.

Lines and blocks

Lines end at LF; a CR before the LF is ignored, and a lone CR elsewhere is a blank shown as a space. Blanks are spaces, tabs and CRs, and a line of only blanks is a blank line. A byte order mark at the very start of an article is ignored. The text is a sequence of blocks separated by blank lines. Markers count only at the very start of a line, and a block also ends before a line it cannot hold, which then starts the next block.

BlockA line that starts with
Heading# and a space
Subheading## and a space
List item- or * and a space
Preformattedfour spaces or a tab
Fencethree backquotes
Tablea bar, |
Paragraphanything else

Paragraphs

    A paragraph's lines are joined
    with spaces and wrapped to the
    reader's width.

A paragraph's lines are joined with spaces and wrapped to the reader's width.

The blanks at the start of each line are dropped. A line that starts no other block continues the paragraph, so a paragraph needs no blank line before a heading, a list or a table that follows it.

Headings

    # A heading
    ## A subheading

A heading

A subheading

Each is one line; the blanks after the marker are dropped. The sections of this article are subheadings.

Lists

    - First item.
    - Second item, whose next line
    continues it.
    * A star works as well.

Lists have one level. Ordinary lines after an item continue it, joined as in a paragraph.

Preformatted blocks and fences

A line indented by four spaces or a tab starts a preformatted block, which holds it and the indented lines after it. They are shown as written, leading blanks included, in a monospaced face, and never wrapped: the reader's column holds about 64 monospaced characters, and longer lines are cut off.

    for (i = 0; i < 10; i++)
        draw(i);
    for (i = 0; i < 10; i++)
        draw(i);

A blank line ends a preformatted block. A fence keeps blank lines: it opens with a line of three backquotes and ends at a line of three backquotes followed only by blanks. The opening and closing lines are not shown. Text after the opening backquotes (an info string) is ignored, except path, which makes a figure. A fence with no closing line runs to the end of the article.

    ```text
    Shown as written,
    blank line included.
    ```
Shown as written,

blank line included.

To show a fence's own source, as above, indent it: an indented line of backquotes is preformatted text, not a fence.

Code spans

    Call `wait_frame` once a frame.

Call wait_frame once a frame.

A code span is a backquote, 1 to 200 bytes holding no backquote and no line break, and a backquote (the bytes as written: in a table cell \| counts as two). It counts in paragraphs, list items, headings and table cells, and is shown in a monospaced face without the backquotes. A link inside a code span is not a link. A backquote that starts no code span is ordinary text, as is every backquote in a preformatted block or a fence. There is no other inline markup: * and _ are ordinary text.

These are links wherever text is shown, also in preformatted blocks, fences and table cells:

FormTarget
terse: and 64 hex digitsAn article, by blob ID
terse:feed/ and 64 hex digitsA feed, by key
terse:feed/, the key, @ and hintsA feed, with the relays that hold it
terse:program/ key / nameA program, by publisher and name
[text](target)Any of these, shown as the text

The hex digits are lowercase. A link must not follow an ASCII letter or digit, and the 64 digits must not be followed by one.

Give a feed's address rather than its bare key, so that readers who use other relays find it: after the key, @ and one or two relays, host or host:port, separated by a comma (no spaces), as in terse:feed/<key>@relay.example.org or terse:feed/<key>@relay.example:9000,[2001:db8::7]. terse feed address prints yours. The hints are the longest run of letters, digits, ., -, :, , and brackets after the @, less every ., , and : at its end, so a sentence may end right after an address. If that is not one or two valid hints (three hints, a bad port), the link is the key alone and the rest is text; a reader that knows no hints does the same, so the link always leads to the feed.

Articles do not link to the web. A web address such as https://example.org is ordinary text, shown as written and not followed, and so is a link with text whose target is not one of the terse: forms: all of [Example](https://example.org) stays as you see it, brackets and parentheses included. Write a web address as plain text if a reader needs it.

Written for real, a bare link to an article (the manual's page on figures), a feed, a feed with a hint, the built-in sketch program, and a link with text to another part of this manual:

terse:95aa09…e7cf04

terse:feed/0000000000000000000000000000000000000000000000000000000000000000

terse:feed/0000000000000000000000000000000000000000000000000000000000000000@relay.example.org.

terse:program/0000000000000000000000000000000000000000000000000000000000000000/sketch

Read the page device next.

The source of the last one is:

    Read [the page device](terse:<64 hex digits>) next.

The reader shortens a bare terse: link to its first and last six digits. A built-in program has the all-zero key and is named by its image's title.

A program's name is the run of bytes A..Z, a..z, 0..9, -, ., _, ~ and %XX (two hex digits, either case) after the slash, less every final dot (Pad... names Pad). Each %XX stands for byte XX; write every other byte (a space, a non-ASCII letter, a final dot) that way. The decoded name must be a valid display name: 1 to 48 bytes, no control characters, no whitespace first or last. A program named Sketch pad is:

    terse:program/<64 hex digits>/Sketch%20pad

A link with text is [, the text, ], (, the target, ), all on one line. The text is 1 to 200 bytes as written (\| in a table cell counts as two) holding no [, ], backquote or link; the target is exactly one link, with no blank. Brackets that do not make a whole link with text are ordinary text, and links inside them count as bare links. Where links and code spans would overlap, the one that starts first counts.

Tables

    | Key | Does | Notes |
    |---|:--:|--:|
    | Esc | back | `\|` is a bar |
    | Tab | next link |
    | T | publish | a test | extra |
KeyDoesNotes
Escback| is a bar
Tabnext link
Tpublisha test

A table is consecutive lines that start with |. Each line is a row, cut into cells at every | not preceded by a backslash, after the leading |, the trailing blanks and a trailing unescaped | are dropped; blanks around each cell are dropped. In a cell \| stands for a bar, also in a code span; any other backslash is itself. Each cell is one line of text, in which links and code spans count.

The first row's cell count, at most 8, is the number of columns. Later rows lose cells beyond it and get empty cells where they have fewer, as the last two rows above show.

If the second line holds only |, -, : and blanks and at least one -, it is an alignment row: it is not shown, the first row becomes a header, and its cells align the columns: :--: centres, --: aligns to the end, anything else to the start. Without one, every column is aligned to the start and there is no header. Keep tables narrow (2 to 4 short columns): wide ones are squeezed and their text wrapped.

Figures

A fence whose info string is path, followed by a width and a height in units (each 1 to 4 digits with no sign, from 1 to 1024), is a figure drawn from SVG path data. A column of the recommended width, about 68 characters of body text, is 512 units wide.

    ```path 200 60
    fill #2b3a55 stroke none M0 0 H200 V60 H0 Z
    fill #98c379 stroke fg 2 M20 50 L60 10 L100 50 Z
    fill none stroke #e5c07b 3 M120 50 Q150 0 180 50
    ```

The panel, a green triangle with a light outline, and a yellow curve. In brief:

Paths are filled with the non-zero rule, then stroked with round joins and ends, later ones over earlier ones. Anything malformed, or a missing closing line, shows the figure as its source text, which is why a figure still reads as text where it cannot be drawn. This reader's column is 512 units, so a unit is one screen unit; it shrinks a figure wider than the column to fit, uniformly. A reader with a narrower column scales figures down in proportion to it, and no reader draws them larger than that unless it enlarges its text the same way. The full rules are in ARTICLE.md; how the reader hands figures to the page device is in figures on the page.

Size and publishing

Keep articles to a few kilobytes. A host downloads an entry's article without being asked when it is at most 16,384 bytes (the user may change this limit), so such articles open at once; larger ones are fetched when opened. The reader shows at most 48 KiB of an article (a longer one ends with a note saying how much is shown), and does not open a linked article larger than that.

Publish a file in your own feed with the command line tool:

    terse feed publish hello.txt --title "Hello"

It puts the blob, publishes the next entry of your feed and prints seq N blob <id>; --reply-to <blob id> marks a reply. The entry's title is what timelines show. Like the other feed commands it takes --relay, --store and --config. In the reader, T publishes a test article of its own, not your text; a program that publishes asks the host, which asks you.

How the reader shows it

In a column 512 units wide: paragraphs in 15-unit sans (about 68 characters a line), headings 21 bold, subheadings 17 bold, list items indented 10 behind a bullet, preformatted lines and fences 13-unit monospace, figures centred. The first 512 links get the link colour; Tab moves between them and Enter follows one. The reader builds a page document from the article; how such a document is laid out is in the page device.

Other readers may look different: ARTICLE.md fixes what each construct means, not fonts, sizes or spacing, and a reader may show tables as paragraphs and figures as their text. Write so the article reads well either way.