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

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.