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

8 Reading the HelpTag
Document Type Definition

Contents of Chapter:

Document Type Definition

Helptag 1.3 DTD

DTD Components

Element Declarations
Element Declaration Keywords
Attribute List Declarations

Formal Markup

Formal Markup Caveats
Explicit Hierarchy of Elements
File Entity Declarations

Processing Formal Markup

This chapter explains how to read the HelpTag 1.3 Document Type Definition (DTD) and how to use it to create fully compliant Standard Generalized Markup Language (SGML) help files.

Document Type Definition

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.

Helptag 1.3 DTD

The Helptag 1.3 DTD tag set and its associated rules are referred to as formal markup. The DTD conforms to the Standard Generalized Markup Language (SGML) ISO specification 8879:1986. This means that you can use formal markup to create help files that are SGML compliant.

Appendix A contains the complete DTD specification. The DTD is also available in the Developer's Toolkit. It is located in the /usr/dt/dthelp/dthelptag/dtd directory and is named helptag.dtd.

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>

Formal Markup

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.

See the section "Write Help Topics with HelpTag" for a description of shorthand and formal markup, and structured editors.

Formal Markup Caveats

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.

<chaphead>
      <head>
             <partext>Front Panel Help</partext>
      </head>
</chaphead>

Notice the additional tags, <head> and <partext>; these are subcomponents of the <chaphead> element. Each of these elements requires an explicit start and end tag.

Explicit Hierarchy of Elements

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.

<!ELEMENT chapter - - (chaphead, text?, (s1*, rsect*)) >
<!ELEMENT chaphead - - (head, abbrev?)
                       -(memo | location | idx | footnote) >
<!ELEMENT head - - (partext)
                   -(memo | location | idx)>
<!ELEMENT partext - - ((#PCDATA . . . ))>

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. Select Common 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>

File Entity Declarations

To declare a file entity in formal markup, use this syntax:

<!entity entityname SYSTEM "filename">

Where entityname is the name of the entity and filename is the name of the file. The keyword SYSTEM is required.

Note: To use entity declarations previously created for shorthand markup, you must replace the FILE parameter with SYSTEM.

Example

Here are the entity declarations for a help volume that consists of three text files and contains a graphic image.

<!entity MetaInformation SYSTEM "metainfo>"
<!entity BasicTasks SYSTEM "basics">
<!entity AdvancedFeatures SYSTEM "advanced">
<!entity process_diagram SYSTEM "process.tif">

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.

Generated with CERN WebMaker

8 Reading the HelpTag Document Type Definition

See Also

Examples

Explicit Start and End Tags

Example

Example

Processing Formal Markup

8 Reading the HelpTag
Document Type Definition