Candidate

1.0 (2018-02-19)

Inline Content

Ducktype allows all semantic inline content, along with attributes, using a single, consistent syntax.

Notes

  • Inline markup is parsed after all structural and block markup is parsed.

  • Inline elements start with $ followed by a name.

  • Inline element content is surrounded by parentheses, and may contain further inline markup.

  • Inline elements may have an attribute list between the name and the content.

  • Inline may contain entity references. An entity reference is $ followed by the entity name followed by ;. When used inline, entities may contain further inline markup.

Examples

Use a simple inline element:

Click $gui(Apply).
Click <gui>Apply</gui>.

Nest inline elements:

Your home directory is $file(/home/$var(username)/).
Your home directory is <file>/home/<var>username</var>/</file>.

Use attributes on an inline element:

Read the $link[href=http://projectmallard.org/ducktype/1.0/](Ducktype specification).
Read the <link href="http://projectmallard.org/ducktype/1.0/">Ducktype specification</link>.

Use attributes on an empty inline element:

The Ducktype specification is at $link[href=http://projectmallard.org/ducktype/1.0/].
The Ducktype specification is at <link href="http://projectmallard.org/ducktype/1.0/"/>.

Specification

Inline content is parsed after all block and structural parsing is finished. Consequently, mismatched parentheses or brackets in inline content has no effect on block structure.

An inline string is parsed for inline elements and entity references. Inline markup starts with $ (U+0024) followed by a name. If the name is followed by either a left square bracket [ (U+005B) or a left parenthesis ( (U+0028), it is an inline element. If the name is followed by a semicolon ; (U+003B), it is an entity reference.

Inline strings may also contain character escapes. If the character $ (U+0000) is followed by one of $ (U+0024), * (U+002A), = (U+003D), - (U+002D), @ (U+0040), [ (U+005B), ] (U+005D), ( (U+0028), ) (U+0029), " (U+0022), or ' (U+0027), that two-character sequence is replaced by the second character.

If an inline element name is followed by [, then that square bracket is the start of an attribute list. The attribute list continues until it is closed. If the next characters after the closing right square bracket is (, then that parenthesis starts the element content. Otherwise, the element is empty, and has only attributes.

If an inline element has a left parenthesis following either the element name or the optional attribute list, that parenthesis starts the inline element content. Inline element content is parsed as an inline string, and may contain further inline elements or entity references. The element content may contain parenthesis, either as markup for further inline elements, or an non-markup characters in the actual content. The parser must track non-markup parentheses, and close the element content when the first unbalanced, unescaped right parenthesis is reached. For example, the following is correct markup:

$em((parenthesized))
<em>(parenthesized)</em>

If the character $ (U+0024) is followed by a name and the character ; (U+003B), then the name is an entity name, and the entire entity reference is replaced according to the following rules:

  • If the name is a user-defined entity, the content of that entity is parsed as an inline string, and the result is used. Note that each entity is parsed in its own subcontext, so you cannot span an entity reference across multiple entities. Parsers must detect cycles in entity references and produce an error.

  • Otherwise, if the name is defined in XML Entity Definitions for Characters (2nd Edition), the corresponding value is used.

  • Otherwise, if the name consists only of characters in the ranges 0-9, a-f, and A-F, that value is interpreted as a hexadecimal number, and the Unicode character with that code point is used.

  • Otherwise, the entity is unrecognized, and parsers must produce an error.

© 2015-2018 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard