# Display Specification DTD

The Display Specification DTD (`xds.dtd`) specifies the kinds of tags that can be included in your XDS document. In addition, the DTD tells a validating parser which tags are valid, and in what arrangements. A DTD tells both validating and non-validating parsers where text is expected. This lets the parser determine whether the whitespace it sees is significant or ignorable.

When creating or editing an XDS, the XML tags used, their attributes and arrangement must conform to `xds.dtd`. If the XDS is invalid, &app; may throw an exception and exit.

## Anatomy of a Display Specification

A display specification is an XML file, it therefore has an XML prolog like such.

    <?xml version="1.0"?>

When creating or editing an XDS the Display Specification DTD (`xds.dtd`) should be declared so that your custom XDS may be validated against it. The Document Type Declaration of a display specification always defines the "root" as `dispspec`.

The Document Type Declaration does not have a PUBLIC Identifier as they are not strictly required for XML documents. The DTD location is therefore specified using the SYSTEM Identifier as shown in the following example.

    <!DOCTYPE dispspec SYSTEM "xds.dtd">

&app; does currently validate XDS files at run-time.

## Element Reference

### collapseto

The `collapseto` element is currently unsupported.

When supported, setting `collapseto` causes the element wrapper to become part of the parent node element wrapper. The vertical line of the parent element wrapper is punctuated or outdented at the point where the element with `collapseto` set is located.

#### Attributes

None Applicable

#### Parents

#### Children

None Applicable

#### Example

See .

### description

A paragraph describing the Document Type annoted by the XDS.

#### Attributes

Name | Value | Description
--- | --- | ---
&row_xml_lang_attrib;

#### Parents

#### Children

None Applicable

#### Example

See

### dispspec

This is the root element of the &app; Display Specification Document Type.

#### Attributes

None Applicable.

#### Parents

None Applicable

#### Children

, , ,

#### Example

    <dispspec>
        <metadata>
            . . .
        </metadata>
        <serialisation>
            . . .
        </serialisation>
        <document-models>
            . . .
        </document-models>
        <element-list>
            . . .
        </element-list>
    </dispspec>

### document-models

A wrapper element for `external-document-model`. Mutiple `external-document-model` elements may be specified.

#### Attributes

None Applicable.

#### Parents

#### Children

#### Example

    <dispspec>
        . . .
        <document-models>
            <external-document-model type="dtd" public-id="" system-id=""/>
        </document-models>
        . . .
    </dispspec>

### element

An XML element.

#### Attributes

&tbl_element_attrib;

#### Parents

#### Children

, , , ,

#### Example

    <element-list>
        <element tag="" type="" color="" filename-xpath="" icon="" \
            ns="" plugin-id="" whitespace="">
            <name xml:lang=""> . . . </name>
            <short-desc xml:lang=""> . . . </short-desc>
            <property-dialog plugin-id=""/>
            <header-info tag="" xpath=""/>
            <key-value-list>
                . . .
            </key-value-list>
        </element>
        . . .
    </element-list>

### element-list

A wrapper element for element types.

#### Attributes

None Applicable.

#### Parents

#### Children

, , ,

#### Example

    <dispspec>
        <element-list>
            <element tag="" type="" color="" filename-xpath="" icon="" \
                ns="" plugin-id="" whitespace="normalize">
                . . .
            </element>
            <plugin-element tag="" color="" filename-xpath="" icon="" \
                ns="" plugin-id="" whitespace="normalize">
                . . .
            </plugin-element>
            <span-element tag="" color="" filename-xpath="" icon="" \
                ns="" whitespace="normalize">
                . . .
            </span-element>
            <structural-element tag="" color="" filename-xpath="" icon="" \
                ns="" whitespace="normalize">
                . . .
            </structural-element>
        </element-list>
    <dispspec>

### external-document-model

Specifies the Document Type Definition (DTD) annotated by this Display Specification (XDS).

#### Attributes

Name | Value | Description
--- | --- | ---
type | dtd relax-ng-schema w3c-schema | text
public-id | value | The PUBLIC Identifier by which the Documen Type is recognized.
system-id | value | The SYSTEM Indentifier by which the Document Type is to be recognized.

#### Parents

#### Children

None Applicable

#### Example

See

### format

text

#### Attributes

None Applicable

#### Parents

#### Children

None Applicable

#### Example

See .

### header-info

Defines title content for nodes shown in the outline tree view and the element wrappers shown in the page view. Node content is comprised of two parts [element name] : [title] where:

- [name] is derived from `name`.

- [title] is derived from either the value of `tag` or the result of `xpath`.

#### Attributes

Name | Value | Description
--- | --- | ---
tag | An element name from the anotated Document Type. | When an element name is provided &app; will search for a child node whose name corrsponds to the value of `tag` and return the value of the next child node for [title].
xpath | value | An XPath expression that can be used to return a string. The resulting string is used for [title].

#### Parents

#### Children

None Applicable

#### Example

See .

### key-value-list

text

#### Attributes

None Applicable.

#### Parents

, , ,

#### Children

#### Example

    </structural-element>
        . . .
        <key-value-list>
           <key-value-pair key="" value=""/>
        </key-value-list>
        . . .
    </structural-element>

### key-value-pair

text

#### Attributes

None Applicable.

#### Parents

#### Children

None Applicable

#### Example

See

### metadata

A wrapper for elements that provide data about the Document Type which the XDS annotates.

#### Attributes

None Applicable.

#### Parents

#### Children

,

#### Example

    <dispspec>
        <metadata>
            <name xml:lang=""> . . . </name>
            <description xml:lang=""> . . . </description>
        </metadata>
        . . .
    <dispspec>

### name

The displayed name of an object.

#### Attributes

Name | Value | Description
--- | --- | ---
&row_xml_lang_attrib;

#### Parents

, , , ,

#### Children

None Applicable

#### Example

See , , , ,

### plugin-element

text

#### Attributes

&tbl_element_attrib;

#### Parents

#### Children

, , , ,

#### Example

    <element-list>
        <plugin-element tag="" type="" color="" filename-xpath="" icon="" \
            ns="" plugin-id="" whitespace="">
            <name xml:lang=""> . . . </name>
            <short-desc xml:lang=""> . . . </short-desc>
            <property-dialog plugin-id=""/>
            <header-info tag="" xpath=""/>
            <key-value-list>
                . . .
            </key-value-list>
        </plugin-element>
        . . .
    </element-list>

### property-dialog

text

#### Attributes

Name | Value | Description
--- | --- | ---
plugin-id | value | text

#### Parents

, , ,

#### Children

None Applicable

#### Example

See , , ,

### serialisation

text

#### Attributes

None Applicable

#### Parents

#### Children

#### Example

    <dispspec>
        . . .
        <serialisation>
            <format extension=""/>
        </serialisation>
        . . .
    </dispspec>

### short-desc

A short description of the element specified in `tag`.

#### Attributes

Name | Value | Description
--- | --- | ---
&row_xml_lang_attrib;

#### Parents

, , ,

#### Children

None Applicable

#### Example

See , , ,

### span-element

text

#### Attributes

&tbl_element_attrib;

#### Parents

#### Children

, , , ,

#### Example

    <element-list>
        <span-element tag="" type="" color="" filename-xpath="" icon="" \
            ns="" plugin-id="" whitespace="">
            <name xml:lang=""> . . . </name>
            <short-desc xml:lang=""> . . . </short-desc>
            <property-dialog plugin-id=""/>
            <header-info tag="" xpath=""/>
            <key-value-list>
                . . .
            </key-value-list>
        </span-element>
        . . .
    </element-list>

### structural-element

text

#### Attributes

&tbl_element_attrib;

#### Parents

#### Children

, , , ,

#### Example

    <element-list>
        <structural-element tag="" type="" color="" filename-xpath="" icon="" \
            ns="" plugin-id="" whitespace="">
            <name xml:lang=""> . . . </name>
            <short-desc xml:lang=""> . . . </short-desc>
            <property-dialog plugin-id=""/>
            <header-info tag="" xpath=""/>
            <key-value-list>
                . . .
            </key-value-list>
        </structural-element>
        . . .
    </element-list>