Informational Elements

Informational elements provide metadata for pages, sections, and certain block elements. Ducktype provides a special syntax to write informational elements.

Notes

Informational elements follow a page or section header or a block declaration.
An informational element is declared with a leading @ character, followed immediately by the name of the element.
The informational element name may be immediately followed by an attribute list.
The remaining content after the element name and optional attribute list is element content and is parsed as inline content.
An informational element may have child elements, which also use the informational element syntax, indented on subsequent lines.

Examples

Create a page with a guide link:

= My Page Title
@link[guide >index]

Add a link title using inline content in an informational element:

= My Page Title
@link[guide >index]
@title[link] My Page Link Title

Use nested informational elements to record credits:

= My Page Title
@credit[author]
  @name Rupert Monkey
  @email rupert@example.com

Specification

An info segment is a sequence of one or more informational elements. An info segment may follow a page or section title, subtitle, or attribute list (although it may not be between them). An info segment may also follow a block declaration. It begins with a line (possibly indented) starting with the @ character. Each line that starts with @ is an informational element. The Mallard info element is implicit.

If the first informational element is indented, then the outer and inner indent of the implicit info element is set to that indentation level. For block info segments, the first informational element also sets the inner indent of the containing block because it's the first line after the declaration. The info element ends in the following cases:

A line is encountered with an indent that is less than the outer indent of the info element.
A line is encountered with an indent that is equal to the outer indent of the info element that does not start with the @ character.
A blank line is encountered in a block info segment (but not for pages and sections) and the outer indent of the info element is the same as the outer indent of the containing block. This is a consequence of the handling of newlines in block elements with unindented child content. Blank lines do not close the info element if it is indented.

The @ character must be followed by a name. The name may be followed either by a left square bracket or whitespace. If the name is followed by a left square bracket, an attribute list is opened. There may be text content after the attribute list or name. If the element is a leaf element, the text is added as direct text content of the element. Otherwise, a Mallard p element is implicitly created.

If the line after an informational element is indented beyond the outer indent of that element, that line's indentation becomes the inner indent of the element. Subsequent non-blank lines continue to be child content as long as they are indented to at least this level. Further indentation may create child elements of child elements.

If a line in the info segment does not start with the @ character, it is text content. If the current element is not a leaf element, an external element, or a tree item without child items, then a Mallard p element is implicitly created with the outer and inner indent set to the indentation level of the line. If the line is the first line after an info line and a p element was already implicitly created due to text on the same line as the informational element, the outer and inner indent of that implicit p element is set to the indentation level of the line. If the current element is a leaf element, the line is added to the element's text content.

If a blank line is encountered in an informational leaf element, then the blank line closes that element, unless it is a verbatim element with an inner indent greater than its outer indent. If the element is an indented verbatim element, the blank line is added to the content.

A leaf informational element may have an inner indent equal to its outer indent in which it consumes subsequent text lines (without a leading @ character) until a blank line or a line with a smaller outer indent. A non-leaf informational element cannot have any child content without an extra inner indent. Note that this is different from the behavior of block elements.