Common Desktop Environment: Help System Author's and Programmer's Guide

DTD Components

The DTD defines each of the HelpTag elements described in previous chapters in a technical notation. This section introduces some key terms and explains how to read the syntax of the element notations. It does not attempt to fully describe each section of the DTD.

Element Declarations

The DTD defines each element in an element declaration. The declaration uses a precise notation to describe an element, its required components, and any elements it can or cannot contain. An element may also have characteristics defined in an attribute declaration, which is discussed in the section "Attribute List Declarations".

The syntax of an element declaration is:

<ELEMENT element_type minimization (content model) >

Where:

element_ type: Specifies the element name, which is also used as the tag name. For example, the tag for the element type head is <head>.
minimization: A two-character entry that indicates whether a start or an end tag is required. The first character represents the start tag; the second character represents the end tag. A space separates the two characters. The letter o means that the tag is optional. A - (minus sign) indicates the tag is required. For example, an entry like this, - - , indicates that the element requires both start and end tags. The DTD for Helptag 1.3 requires start and end tags for every element.
content model: Specifies a list of the required and optional elements that the element type can contain. It defines the sequence of elements and, if applicable, the number of occurrences that may occur.

The content model uses these notations:

|: A vertical bar represents "or".
+: Element must appear at least once. It can be repeated.
*: Element can appear zero or more times.
?: Element can appear zero or one time.
,: A comma describes sequence, that is, the element type must be followed by the element specified after the comma.
+ (element_ type(s)): The + (plus sign) indicates that the listed element or elements can be used within the element type or within any of the elements it contains. It is called an inclusion. Parentheses are used to enclose one or more elements.
- (element_ type(s)): A - (minus sign) indicates that the listed element or elements cannot be used within this element, or within any of the elements it contains. It is called an exclusion. Parentheses are used to enclose one or more elements.

Examples

Each example contains a word description for the element declaration provided. Required start and end tags are assumed.

A chapter requires a <chaphead> followed by text. A chapter can contain zero or more s1 elements followed by zero or more rsect elements.
```
<!ELEMENT chapter - - (chaphead, text, (s1*, rsect*)) >
```
A chaphead requires a head followed by an optional abbrev. A chaphead cannot contain these elements: memo,location, or idx.
```
<!ELEMENT chaphead - - (head, abbrev?)
                        -(memo | location | idx) >
```
The paragraph element requires a start tag (-) and an end tag (-). It can contain an optional head (?) followed by the partext element. newline elements can be used within p or any of the elements it contains.
```
<!ELEMENT p - - (head?, partext) +(newline) >
```
A note contains text. It can have an optional head. A note cannot contain these elements: note, caution, or warning.
```
<!ELEMENT note - - (head?, text)
                    -(note | caution | warning) >
```
A list may contain an optional head. It requires at least one item, which can be repeated.
```
<!ELEMENT list - - (head?, item+) >
```
The book element declaration uses an exclusion to specify that it cannot contain another book element.
```
<!ELEMENT book - - (partext) -(book) >
```

Element Declaration Keywords

Some elements include a keyword in the element declaration that describes the data content of the element. Three keywords appear in the DTD: EMPTY, CDATA, and #PCDATA.

EMPTY: Specifies that the element has no data content that will be displayed in the online information. newline and xref elements are examples.
CDATA: Represents "character data"; that is, the data content of the element is not recognized as markup.
#PCDATA: Represents "parsed character data"; that is, the data content may include both text and markup characters that the Help System parser interprets accordingly.

Attribute List Declarations

An attribute list declares additional properties that further describe an element. An attribute list declaration has the syntax:

<!ATTLIST element_type attribute_values default_value>

For example, a list element has four attributes: type, ordertype, spacing, and continue. Values for each type are declared. The last column shows the default values. Because only one value exists for the continue attribute, a default value is omitted.

<!ATTLIST list type      ( order 
                           bullet
                            plain
                            check )       bullet
               ordertype ( ualpha
                            lalpha
                            arabic
                            uroman
                            lroman )      arabic
                spacing   ( tight
                             loose )      tight
                continue  (continue)    #IMPLIED >

This markup creates a numbered list (uppercase alphabet) that supplies extra spacing between list items.

<list order ualpha loose>
   <item>
      <text>
        <p>
          <partext>Introducing the Front Panel></partext>
        </p>
      </text>
     </item>