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.`

#### See Also

- `dthelptagdtd(4)``man page`

## 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