A Document Type Definition (DTD) defines a set of elements to create a structured (or hierarchical) document. The DTD specifies the syntax for each element and governs how and where elements can be used in a document.

See Also

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.

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.

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.

Using a structured editor is the best approach for creating formal markup. After learning the basic set of elements, an author can get started. This is done by choosing elements from a menu. In response, the structured editor generates all of the tags required for each element. In addition, the application verifies that the structural framework being created conforms to the Document Type Definition.

Shorthand and formal markup share a common set of elements, such as
chapter, section, head, list, paragraph, and so forth. However, formal markup differs from shorthand markup in these important ways:

Every element requires a start and an end tag.

Tags for each subcomponent of an element must be entered.

The / (forward slash) is the end tag delimiter in formal markup. End tags use this format, </tagname>.

Entity declarations use the SYSTEM parameter instead of the FILE parameter used in shorthand declarations.

Explicit Start and End Tags

Each element, its component parts, and elements it contains must be explicitly tagged. For example, here is the formal markup for a chapter head. To read this, and other markup examples easily, tags are indented. Indentation is not required in actual markup.

Each element declaration contributes to a set of rules that governs how and where elements can be used. Because elements contain other elements, which may contain other elements, a document is a hierarchy of elements. At the top level, <helpvolume> is a container for every other element.

To decide what markup is necessary to create a help topic, you need to become familiar with the rules. For example, suppose you want to create a chapter. First, look at the declaration for chapter listed below. It specifies that a chaphead is required. Next, look at the rules for chaphead. It, in turn, requires a head. Consequently, look at the declaration for head, and continue until you have reached the last nested element--in this case, partext. Until you are familiar with the elements you commonly use, this approach will help you enter markup correctly.

Using a structured editor minimizes what an author needs to know about the DTD. The editor application "reads" the DTD and creates each element's required tags, many of which are intermediate structural tags.

Example

This formal markup sample is an excerpt from the desktop Text Editor help volume. To view the corresponding online information, choose the Help Viewer in the Front Panel. SelectCommon Desktop Environment and then choose Text Editor Help from the listed volumes. In the Text Editor volume, choose Text Editor Tasks and then To Open an Existing Document.

Indentation is used in this example to make it easier to read the text and corresponding element tags.

<s2 id="TOOPENANEXISTINGDOCUMENT">
<chaphead><head>
<partext>To Open an Existing Document</partext>
</head></chaphead>
<text>
<p>
<partext>You can use Text Editor or File Manager to open an existing
document.
</partext></p>
<idx><indexprimary>
<partext>document</partext></indexprimary>
<indexsub>
<partext>opening</partext></indexsub></idx>
<idx><indexprimary>
<partext>opening</partext></indexprimary>
<indexsub>
<partext>existing document</partext></indexsub></idx>
<procedure>
<chaphead><head>
<partext>From Text Editor</partext>
</head></chaphead>
<text>
<list type="ORDER">
<item><text><p>
<partext>Choose Open from the File menu.</partext></p>
<p>
<partext>The Open a File dialog box lists files and folders on your
system.You can browse the documents listed, or change to a new folder
to locate other files on your system.</partext>
</p></text></item>
<item><text><p>
<partext>Select the document you want to open in the Files list or
type the file name in the Open a File field.</partext></p>
<p>
<partext><emph><partext>Or,</partext></emph> if the document is not
in the current folder, first change to the folder that contains your
document. Then choose a name in the Folders list or type the path
name of the folder you wish to change to in the Enter path or folder
name field.</partext></p></text></item>
<item><text><p>
<partext>Press Return or click OK.
</partext></p></text></item></list>
<figure tonumber="NONUMBER" entity="TEXTEDITOROPENFILE">
</figure></text></procedure>
<procedure><chaphead><head>
<partext>From File Manager</partext>
</head></chaphead>
<idx><indexprimary>
<partext>opening</partext></indexprimary>
<indexsub>
<partext>document from File Manager</partext></indexsub></idx>
<idx><indexprimary>
<partext>document</partext></indexprimary>
<indexsub>
<partext>opening from File Manager</partext></indexsub></idx>
<idx><indexprimary>
<partext>File Manager</partext></indexprimary>
<indexsub>
<partext>opening document</partext></indexsub></idx>
<text>
<list type="BULLET">
<item><text><p>
<partext>Display the document's file icon in a File Manager
window.</partext>
</p></text></item>
<item><text><p>
<partext>Do <emph><partext>one</partext></emph> of the
following:</partext></p>
<list type="BULLET">
<item><text><p>
<partext>Double-click the document's file icon.</partext>
</p></text></item>
<item><text><p>
<partext>Select the document, then choose Open from the Selected
menu.</partext>
</p></text></item>
<item><text><p>
<partext>Drag the document to Text Editor's control in the Front
Panel.</partext>
</p></text></item></list></text>
</item></list><text> </procedure>
<procedure><chaphead><head>
<partext>See Also</partext>
</head></chaphead>
<text>
<list type="BULLET" spacing="TIGHT">
<item><text><p>
<partext><xref id="ENTERINGANDEDITINGTEXT"></partext>
</p></text></item>
<item><text><p>
<partext><xref id="TOSAVEADOCUMENTTOTHECURRENTFILE"></partext>
</p></text></item>
<item><text><p>
<partext><xref id="TABLEOFCONTENTS"></partext>
</p></text></item></list></text>
</procedure></text></s2>

Entities are referenced in formal markup exactly as they are in shorthand markup.

Processing Formal Markup

When you process formal markup using dthelptag, you must use the formal command-line option. For example, to process a formal markup file named Icons.ctg in verbose mode, enter this command:

dthelptag -verbose -formal Icons.ctg

Note: The command option specifies the type of markup in the input file. The run-time file created by running dthelptag is always volume.sdl. The online format is identical whether you used shorthand or formal markup.