How the shorthand works

The transcription is written in a plain-text shorthand (“the DSL” in the source code). It is ordinary text with inline markers. Each marker corresponds to a TEI element; the compiler adds the surrounding structure, including the division into words.

///1r //1 Hér hefr upp sǫgu .abbr[kgs]{konungs} ?{Haralds}? ins hár~//2fagra

Principles

Write line by line. The shorthand has no nesting to keep track of. A marker is written where it occurs in the text, and the compiler decides what element wraps what.

The text is the text. Unmarked characters are transcribed text. A marker is only a marker where the syntax says so: .p is a paragraph break only where it stands on its own between spaces, so word.p is ordinary text.

Words are derived. Spaces separate words. Each word becomes a <w> element when the template enables word wrapping, and punctuation becomes <pc>. A small number of markers override word division across lines, pages and written spaces.

Errors are recoverable. The compiler does not stop at the first syntax error. It treats the offending opener as text, records a diagnostic with a line and column, and carries on, so one unclosed bracket does not hide every later mistake. Errors are underlined in the editor and prevent save and export until they are fixed.

A first reading

You type	Meaning	TEI
//	Line break	<lb/>
///1v	Page break	<pb n="1v"/>
.abbr[kgs]{konungs}	Abbreviation with its expansion	<choice><abbr>kgs</abbr><expan>konungs</expan></choice>
?{Haralds}?	Unclear reading	<unclear>Haralds</unclear>
[...3<ok>]	Gap of three characters, with ok supplied	<gap …/><supplied>ok</supplied>
-{hans}-	Deletion	<del>hans</del>
+{sona}+	Addition	<add>sona</add>
:thorn:	Special character (MENOTA/MUFI entity)	&thorn;
hár~//2fagra	A word continued across a line break	<w>hár<lb n="2"/>fagra</w>

The rest of this section explains each family of markers:

• Line and page breaks
• Editorial marks
• Abbreviations
• Word division

The shorthand cheat sheet puts every marker on one page.

Whitespace and line endings

The shorthand is a text file. Line endings are not significant to the compiler in the way line markers are: pressing Enter in the editor does not produce a <lb/>. Only // does. You can therefore wrap a long source line in the editor without changing the output.

Whitespace between words separates words. Changes to whitespace that do not affect the encoding do not change an imported TEI file either. See Importing existing files.

Templates decide the surroundings

The shorthand supplies the body of the document. A template supplies the header and the closing markup, and decides whether words are wrapped, whether line breaks are numbered automatically, and whether MENOTA’s three levels are written. The same transcription can therefore be compiled differently for two editions.

Where the compiler can be trusted

The shorthand and the XML are meant to read as the same tokens, one to one. In imported mode this matters especially: the DSL generated from a file and the file’s XML must describe the same words, so that edits can be written back without disturbing the rest. The project tests this correspondence. See Round-trip guarantees.