Parser Directives

Parser directives are special markers at the top of a Ducktype file that provide extra information for the Ducktype parser. Use parser directives to declare namespaces, define entities, manage extensions, and more.

Notes

Pages may have any number of parser directives at the top, each starting with the @ character and immediately followed by the directive name. Additional directive content may follow the directive name after a space. Directive content continues until the end of the line.
A directive that starts with ducktype/ specifies the version of the Ducktype syntax in use and may declare additional syntax extensions.
A directive with the name define defines an entity.
A directive with the name encoding specifies the character encoding of the Ducktype document.
A directive with the name include includes an external file with parser directives.
A directive with the name namespace specifies a prefix for a namespace URI.

Examples

Specify that a page uses version 1.0 of this specification:

@ducktype/1.0

= Page Title

Specify that a page requires version 1.0 of the extension foo in addition to version 1.0 of this specification:

@ducktype/1.0 foo/1.0

= Page Title

Declare and use the namespace prefix if for Mallard Conditionals 1.0:

@ducktype/1.0
@namespace if http://projectmallard.org/if/1.0/

= A Page with Conditionals

[if:if test=target:html]
This is only output to HTML.

Define and use an entity version for the current version of the software you’re documenting:

@ducktype/1.0
@define version 3.26

= A Page with Entities

This page describes MyApp $version;.

Define and use an entity that contains inline markup:

@ducktype/1.0
@define appname $app(MyApp)
@define version 3.26

= A Page with Entities

This page describes $appname; $version;.

Define and use an entity that references other entities:

@ducktype/1.0
@define appname $app(MyApp)
@define version 3.26
@define appvers $appname; $version;

= A Page with Entities

This page describes $appvers;.

Define an entity and use it in an attribute value:

@define mallard http://projectmallard.org/

= A Page with Entities

Read all about $link[>>$mallard;](Mallard).

Specification

A parser directive is a line at the beginning of a Ducktype file that starts with the @ character (U+0040). All directives must occur before the first non-directive markup. However, blank lines may be interspersed with directives.

The directive name must immediately follow the @ character. The directive name is a name. It is followed by either a space or the end of line. Directives may have directive content. The directive content begins with the first non-space character after the directive name and continues to the end of line.

Some directives make use of a first word. The first word of a directive begins with the beginning of the directive content and is terminated by a space or the end of line. The remaining directive content is the directive content following the first word with any leading spaces stripped.

Some directives make use of a word list. The word list is a list formed by splitting the directive content on space characters, with all leading and trailing spaces stripped from words and with no empty words.

This specification recognizes five directive names: ducktype/1.0, define, encoding, include, and namespace. Extensions may recognize additional directives. To avoid conflicts, start extension directive names with the extension prefix and follow them with a colon character (U+003A).

The ducktype/1.0 Directive

@ducktype/1.0
@ducktype/1.0 extension/1.0

The ducktype/1.0 directive specifies that the page is using version 1.0 of this specification. Future versions of this specification may introduce additional syntax and will provide an updated directive to specify use of that version.

A parser must generate an error if it encounters a directive whose name begins with the string ducktype/, other than the ducktype/1.0 directive.

The ducktype/1.0 directive may take a word list as content to specify extensions. Each word should be of the form prefix/version, where prefix is a canonical prefix for the extension and version indicates the version of the extension in use. For example, the first version of an extension to recognize inline AsciiDoc markup might use asciidoc/1.0.

A parser must generate an error if it encounters an extension declaration it does not recognize. Extensions may alter any aspect of parsing, and there is no expectation of graceful fallback behavior for parsers that do not recognize an extension.

Ducktype extensions are not Mallard extensions. Mallard extensions introduce elements and attributes in different namespaces. Mallard extensions can be used in Ducktype by declaring a namespace and using them as normal. Ducktype extensions can change parser behavior and must be declared in the ducktype/1.0 directive.

The define Directive

@define name value

The define directive defines a user-defined entity that can be used in inline content and attribute values. The first word of the directive is the entity name. The remaining directive content is the entity value. The entity value is not parsed when the entity is defined. Rather, the entity value is stored as-is and parsed on use. How it is parsed depeneds on where it is used.

An entity may be defined by multiple directives, in which case the last declaration is used.

Additionally, parsers may provide a way to pass in entity definitions that override those defined in a file. However, those definitions are only valid if an entity with the same name is defined in the file being parsed or in an included directive file. Any definition overrides that are not defined in the file or its includes must be ignored, possibly with a warning.

An entity is referenced in inline content or attribute values with the $ character (U+0024), the name of the entity, and the ; character (U+003B). Note that this entity reference syntax is also used to insert special characters. To learn how to substitute parsed values, see Inline Content and Attribute Lists.

The encoding Directive

@encoding charset

The encoding directive takes a single word that specifies the character encoding of the file being parsed. By default, all Ducktype files are UTF-8, and the case-insensitive value of UTF-8 must be recognized. Parsers are not required to recognize any other encodings.

The encoding directive, if present, should immediately follow the ducktype/1.0 directive. Parsers may recognize a byte order mark at the beginning of a Ducktype file to begin parsing in UTF-16, UTF-32, or another ASCII-incompatible multi-byte encoding. However, the Ducktype file must still have an encoding directive to specify this encoding.

The include Directive

@include filename

The include directive specifies an external file that will be parsed for further parser directives. The directive content must be a single word and specifies a file name, possibly relative to the location of the file with the include directive. The file name may be URL-encoded to encode spaces or other characters. That file is parsed as a list of parser directives, possibly with empty lines. It is an error for the included file to include anything other than parser directives.

If the included file contains a directive whose name starts with ducktype/, it must be the first directive in the included file, and it is parsed for the Ducktype version and parser extensions exactly as it would be for the main parser. However, the Ducktype version and parser extensions only affect the included file.
If the included file contains a define directive, that entity definition is inserted in the main parser context.
If the included file contains an encoding directive, the directive content is a single word that specifies the character encoding of the included file only. Included files do not affect the character encoding of the files that include them.
If the included file contains an include directive, the directive content is a file name that is further parsed for parser directives. If that file name is relative, it is resolved relative to the file that referenced it, not relative to the primary document.

Parsers must attempt to detect recursive includes using absolute paths whenever possible. To prevent symbolic links or redirects from bypassing this detection, parsers may implement an arbitrary recursion depth limit.
If the included file contains a namespace directive, that namespace prefix definition is inserted in the main parser context.

Extensions that recognize additional directives should specify the behavior of those directives in included files.

The namespace Directive

@namespace prefix uri

The namespace directive declares a namespace prefix for block elements, informational elements, inline elements, and attributes. By default, elements are in the namespace http://projectmallard.org/1.0/, and attributes are in the empty namespace.

The first word of a namespace directive is the prefix. The remaining directive content is the namespace URI.

Namespaces work similarly to XML. Parsers can copy the namespace declarations to the root XML output element, then use the prefixed element and attribute names as written in the Ducktype file. However, parsers may output namespaces in a different manner.

Unlike XML, Ducktype namespace declarations can not be set or overridden on individual elements. All namespaces are declared at the top of a Ducktype file or in included directive files. If a namespace prefix is set by multiple directives, the last declaration is used.

As in XML, the xml namespace prefix is automatically bound to the namespace URI http://www.w3.org/XML/1998/namespace. The xml namespace may be declared, but it must not be bound to any other namespace URI.

Additionally, the its namespace prefix is automatically bound to the namespace URI http://www.w3.org/2005/11/its. The its namespace may be declared, but it must not be bound to any other namespace URI.