Embed Notice

• @ indicates a command is incoming.
• @@ escapes the command character and inserts a literal at-sign instead.
• {...} represents a parameter to a command which is textual data. There may be more than one parameter. Textual data may have escapes such as @{ or @} to include a close brace as literal character when there is an imbalance.
• [...] represents a parameter to a commend which consists of Lisp. This is implementation-defined. Lisp data may have escapes such as @[ or @] to include a literal closing bracket when there is an imbalance.
  • These are stolen from Scribble but we omit some of the rather creative ideas for escaping blocks. We’re not writing a whole Lisp module here we’re just structuring data.
• All block based commands start with begin <name> and are finished with end <name>. This allows dumb processors to understand blocks in a document without actually understanding what the processor is going to do with it.
  • Contrast to Texinfo where you have to know in advance that some commands are blocks and some are not.
• Brace and bracket groups are presumed to be balanced. This means count up every time you see [ or { and count down on ] or }. Escapes are only needed if there is intentionally an imbalance of these symbols for some reason.
• As a special case, @c indicates the command until end of line is a comment.
  • Comments may also be a begin/end block but this does not involve any special handling.
• All else should be considered plain text. Plain text must be read with all whitespace exactly intact as the parser sees it. The user or backend will ask if they want any special whitespace processing (such as paragraph formatting) to occur.
  • Authors should use semantic whitespace. This means one sentence per line in a file. One or more consecutive blank lines indicates a paragraph break.

Latex is very similar but the command character is replaced with \ instead of @. I have no problem with processors allowing this via a flag. In such cases the command character is changed all semantics should remain the same (ex. changing the command character to $ means $$ and $[ are the escapes.) These alternatives are considered non-canonical.

Scribble’s creative idea for escapes makes it agitating to parse with readily available tools. Skribe’s syntax is too anemic. Markdown and Asciidoc are specialized for specific kinds of text markup and are not suitable for meta-modeling or writing documents outside their assigned domain. Texinfo’s toolchain is dated–but the syntax is objectively simple and rather easy to build around.

Latex and Booklit are mostly fine

• https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Command-List.html
• https://barzilay.org/misc/scribble-reader.pdf
• https://booklit.page/