Scribble
Created on 2021-01-11T01:57:12-06:00
TODO implement this in janet
- Scribble consists of plain text and markers.
- Markers take the form @command[lisp symbols]{text}.
- All contents are converted to a Lisp list. Plain text becomes strings while markers become S-expressions.
- The contents of balanced brackets are passed as Lisp symbols. So @foo[bar] -> (foo bar)
- The contents of balanced braces are passed as Strings. So @foo{bar} -> (foo "bar").
- Brackets or braces may be omitted.
- "At" symbols may stand alone for comments or literal injections of S-expressions.
- Symbol names can be escaped with @|foo|, primarily used to prevent valid Lisp symbols from getting scooped up when next to prose.
- A backslash before an at or pipe escapes it.
- Pipe strings are for inserting verbatim text. They will consume until the closing string.
- Pipe strings can have custom escapes added between the pipe and bracket. The closing symbol must appear there too--with one edge case: parenthesis, brackets, and chevrons are flipped so open symbols in the opener become close symbols in the closer.
- Pipe strings at the end of a line suppress the line from having its newline trimmed. This is the 'line joiner' convention.
- Strings which appear consecutively in a group are trimmed at both ends and merged together. Strings which consist solely of a new line (blank lines) are not merged; they signify a paragraph break so the strings remain separated.
Keep the following in mind when trying to reason about a Scribble file:
- Groups are looking for their close markers, but will count up and down brackets and braces found inside. They will only close when the symbols are both balanced *and* the right closing sigils are present. This makes it possible to nest markup.
- Text markup is not parsed unless the command you call wants it to be.
Pipe strings
|{do not process my monster truck|} |-farp-{for example, |{ is used to suppress }| code valuation}-farp-|
Comments
@; this entire line is commented Hello @;{stupid person} valued customer! @; "stupid person" is commented
Literal injections of S-expressions
@(florp) @; this will insert a call to "florp"