Chapter 2 : Language Syntax

Lexical Structure

The structure of HDML is described by an abstract syntax using an enhanced BNF:

a ::= b the element a is defined as b
a ::= b ::= c the element a is defined as b or c
b c element b is followed by element c
a | b | c element a or element b or element c
{ a } the element a is optional
{ a } * the element a may appear zero or more times in a row
( a ) + the element a may appear one or more times in a row
abc the characters abc literally
ol(a) an option list with zero or more options of the element a, "Options"

Lexical Structure

HDML 2.0 is nominally an ISO-Latin-1(ISO 8859-1) language. Syntactic elements (delimiters, keywords, option names, and the like) are constrained to US-ASCII printable characters and whitespace so that other 8-bit character encodings can be used as long as:

If the character encoding is not specified, ISO-Latin-1 may be assumed.

With the exceptions described below, white space is used as a delimiter, and is otherwise ignored. HDML white space is defined as US-ASCII newline (10), carriage return (13), space (32) and tab (9).

HDML also supports comments. Comments are treated as white space, and have the following syntax:

In order to disambiguate between syntactic elements and the contents of the decks and cards, HDML uses SGML character and entity references to allow you to quote special characters. The following table lists the available references.

Character/Entity Reference Character
> >
&lt; <
&amp; &
&dol; $
&nbsp; non-breaking space
&# hex hex ; any one-byte character

Character and entity references are not allowed in tag, option, and variable names, but they are allowed in option values and formatted text.


Many of the syntactic elements of HDML have option lists associated with them. Options refine the operation of the elements they are part of. Options that are not defined for an element are ignored.

    ol(valid-option) ::= { valid-option }*
         option-list ::= ol(option)
              option ::= key = value
                 key ::= identifier
               value ::= plain-text
                     ::= " { text }* "
     value-with-vars ::= variable | plain-text
                     ::= " { variable | text }* "

An option list contains zero or more options. Each option is separated by blank-space and optionally followed by blank-space. In the syntax diagrams, option lists are shown as: ol(valid-option) where valid-option is replaced with an element that defines the possible options in this context. ol is a generic syntactic description of option-lists.

Each option is a key and a value. Options be given in any order within the list of options. The key is always an alpha-numeric name that is case insensitive. If the value of an option does not contain whitespace, it may appear directly after the equals sign, otherwise, the value must be quoted. Values are composed of a sequence of text and, if allowed, variable substitutions. In quotes, blank-space (including newlines) is treated literally and is considered part of the value.

In the syntax diagrams, the possible values for various options are specified without quotes. However, quotes are always acceptable around an option value.

Many options have a more restricted set of possible values than represented by the above syntax. See the individual options for details.

HDML 2.0 Specification - 11 APR 1997