Concepts
Like other lightweight syntaxes, paragraphs and other block elements in Ducktype are generally delineated with blank lines. There is a special syntax for titles and subtitles of pages and sections, a syntax for specifying block elements, a syntax for recording informational elements, a syntax for inline elements, and a syntax for special parser directives. All elements are treated as one of these five cases. There are a few shorthand notations, but they can always be defined in terms of some long-form syntax.
The syntax is designed such that block and inline parsing can be done in separate steps. You can parse all section, info, and block content, pushing inline content into strings to parse later. This has a number of implications. In particular, an open inline element would never prevent block syntax.
Indentation is significant in Ducktype. Indentation is how you stay inside of block elements and therefore how you nest block elements. It is not always necessary to use indentation to nest block content. The exact behavior is specified throughout this specification. Indentation is always some number of space characters. Tabs are not considered indentation characters.
In this specification, the following terms are used:
A name is a sequence of NMTOKEN characters.
A newline is either a carriage return (U+000D), a line feed (U+000A), or a carriage return followed by a line feed.
A line is an actual line of text, starting on the character following a newline and going through the following newline (or to the end of the file if the file does not end in a newline).
An indented line is the line after leading spaces have been stripped.
A blank line is a line that contains only whitespace.
The outer indent of a block or informational element is the number of leading spaces on the line that started the element.
The inner indent of a block or informational element is the number of leading spaces required for subsequent elements to be child elements, generally the outer indent of the first child. It's possible for the outer indent and inner indent to be the same. In this case, the first blank line will usually break out of the element except in a few special cases for lists and tables.
In addition, certain elements need special treatment to make implicit paragraphs and other line-oriented features work the way users expect:
A leaf element is a block or informational element that takes inline content rather than further block or info content. Because of Mallard's strict content model, only leaf elements may contain text nodes. The default set of leaf elements is p, screen, code, title, subtitle, desc, cite, name, email, and years.
A verbatim element is a leaf element where whitespace is preserved as written. Newlines are sometimes handled differently in verbatim elements than in non-verbatim elements. The default verbatim elements are code and screen.
A tree item is an item element whose parent element is either a tree element or another tree item. Tree items are peculiar in Mallard. They allow leading inline content without an extra leaf element but then allow a sequence of item elements.
An external element is an element whose namespace URI does not start with http://projectmallard.org/. External elements are allowed to take inline content without an implicit Mallard p element. Extension elements defined on projectmallard.org are expected to work with the leaf elements in the Mallard core, but elements from outside vocabularies (such as TTML or SVG) are not.
