2012-05-10 h10 -- GNUVOLA Trip Log Format Definition

This post documents the gnuvola trip language file format, version 1 (conventionally written with extension ".gtl"), a plain text format with some slightly bizarre syntax. I intend to evolve it even more strangely, at least enough to support its primary purpose: writing about trips. Since it is text, the first thing to specify is the encoding: strictly UTF-8, thanks.

At the beginning of the file, until the first formfeed-newline pair (in C notation ‘\f\n’), are the “tags” for the post, one per line. These are case-sensitive. For example, this is how the beginning of this (source) file appears, with ‘^L’ representing formfeed:

The body of the post comes after the formfeed-newline pair. Paragraphs are separated by two newlines, reminiscent of Thomas Lord's (old?) posting style. Sentences should explicitly end with ‘’ (U+00A0 NON-BREAKING SPACE) (yeah, this is lame -- maybe v2 will be better).

Some paragraphs are special. Their first line begins in column 0 with ‘#\,’ (comma) followed immediately by a processing-instruction sexp that describes the special formatting required. If the sexp is ‘symbol’, then that is taken to be equivalent to ‘(symbol)’.

The first of these processing-instructions is ‘pre’, which arranges to output that paragraph with an HTML ‘pre’ tag, as demonstrated above. Actually, for ‘symbol’ sexp, most HTML elements are acceptable:

Another is ‘cartouche’, which is like ‘pre’, but additionally constructs a border (with Unicode box drawing characters) around the paragraph. The particular border style depends on the first (column 0) character of the subsequent lines (which must be identical):

(define CARTOUCHE-SETS
  '(("│"            ; U+2502 -- BOX DRAWINGS LIGHT VERTICAL
     "┌""─""┐""└""─""┘")
    ("┃"            ; U+2503 -- BOX DRAWINGS HEAVY VERTICAL
     "┏""━""┓""┗""━""┛")
    ("║"            ; U+2551 -- BOX DRAWINGS DOUBLE VERTICAL
     "╔""═""╗""╚""═""╝")
    ("┋"            ; U+250B -- BOX DRAWINGS HEAVY QUADRUPLE DASH VERTICAL
     "▗""┅""▖""▝""┅""▘")))

When rendered, the space between the left border and the paragraph text is reflected also for the right border. For example:

As for parenthetical sexps, the only processing-instruction supported (for now) is ‘~img’, which has a special syntax:

This renders as ‘<div><img class="center" ...></div>’, with ‘TITLE’ serving double-duty as the value for attributes ‘alt’ and ‘title’.

To indicate a (possibly nested) list, start a paragraph with a ‘#\-’ (hyphen) in column 0. For example:

Unfortunately, for now, intervening text (on lines that do not begin with hyphen) is silently ignored.

Within a paragraph (or list header-line), there are basically two kinds of inline markup: hypertext links and ‘code’ decoration. The latter is applied to text between U+2018 and U+2019 (i.e., LEFT and RIGHT SINGLE QUOTATION MARK), as well as for single-line text between a pair of double-quotes ‘#\"’ (U+0022). Hypertext links are indicated using the special syntax:

where ‘^A’ represents ‘C-a’ (U+0001) and so on (yes, somewhat strange, but easy to read in an Emacs buffer). This renders as the expected ‘a’ (anchor) element and furthermore inline, so you can abut punctuation or another link, for ex am ple. Note that whitespace around ‘TEXT’ and ‘URI’ is discarded.

Well, that wraps it up. Obviously, this format is at present as ad-hoc and inflexible as the (prettified) program that processes it, but let's see what happens in the future.

Trip Log 2012-05-10 h10 -- GNUVOLA Trip Log Format Definition