Incomplete

1.0 (2017-02-06)

Parser Directives

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

Notes

  • Pages may optionally have any number of parser directives at the top, each starting with the @ character, 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;.

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 sequence of NMTOKEN characters terminated either by a space or the end of line. Directives may optionally 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 four directive names: ducktype/1.0, define, encoding, include, and namespace. Extensions may recognize additional directives.

Recommendations for extension directives

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

FIXME

FIMME: duck_define.page ??

FIXME: comments, also in includes

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.

It is recommended that 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 is a file name, possibly relative to the location of the file with the include directive. 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 a 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. It is possible that symbolic links or redirects may bypass this detection. Parsers may implement an arbitrary recursion depth limit to overcome this.

  • If the included file contains a namespace directive, that namespace prefix definition is inserted in the main parser context.

If extensions recognize additional directives, they 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, 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 content is the namespace URI.

Namespaces work similarly to XML. Parsers can simply 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. A namespace prefix may be set by multiple directives, in which case the last declaration is used.

As in XML, the xml namespace 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.

© 2017 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