After you have learned the basic set of elements, using a
structured editor is the best approach for creating formal markup.
With a structured editor, the author creates formal markup by choosing
elements from a menu. In response, the structured editor generates
all of the tags required for each element. In addition, it verifies
that the structural framework being created conforms to the Document
Type Definition.
Formal
Markup Caveats |
 |
DocBook is a formal markup language. Nearly every element
requires a start and an end tag. If the start tag is <ElementName>,
the end tag will take the form </ElementName>,with
the /(forward slash) marking it as the end tag.
In formal markup, each element, its component parts, and elements
it contains must be explicitly tagged. For example, here is a schematic
formal markup for a Row in a Table containing two Entries. (For
ease of reading in this and other markup examples, tags are indented.
Indentation is not required in actual markup.)
<row>
<entry align="left" valign="top">
<para>contents
of first entry</para>
</entry>
<entry align="left"valign="top">
<para>contents
of second entry</para>
</entry>
<row> |
Notice that Entry and Para, the subcomponents of the Row,
each have their own start and end tags.
Explicit
Hierarchy of Elements |
|
Each element declaration in the DTD 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, the Part element is
the container for every other element in the help volume.
To decide what markup is necessary to create a help topic,
you need to become familiar with the rules that govern the DocBook
markup laguage.
One way to learn the markup language would be to study the
element declarations for the components you need to use. For example,
suppose you want to create a chapter. First, look at the declaration
for the Chapter element listed below.
<!ELEMENT Chapter - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;), (Index |
Glossary | Bibliography)*) +(%ubiq.gp;) > |
This tells you a Chapter may have a DocInfo component. So
next you look at the declaration for DocInfo, to see how it is constructed.
<!ELEMENT DocInfo - - (Title, TitleAbbrev?, Subtitle?, AuthorGroup+, Abstract*, RevHistory?, LegalNotice*) -(%ubiq.gp;) > |
This tells you that a DocInfo requires at least a Title and
one or more AuthorGroups, and may optionally contain various other
elements. So next you would have check into the declarations for
the Title element and the AuthorGroup element, to see how they are
constructed.
<!ELEMENT Title - - ((%inlinechar.gp;)+) >
<!ELEMENT AuthorGroup - - ((Author | Editor | Collab | CorpAuthor |
OtherCredit)+) >
|
By continuing along in this fashion until you have investigated
all the subcomponents of a Chapter, and all the subcomponents of
the subcomponents, down to the innermost nested element, and mastered
how they work, you could learn how to construct a Chapter.
Fortunately, however, using a structured editor minimizes
what an author needs to know about the DTD and the syntx of the
markup tags. The structured editor application "reads"
the DTD and creates each element's required tags, many of which
are intermediate structural tags.
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 and extra white space is used in this example
to make it easier to read the text and corresponding element tags.
Remember that using indentation and extra white space is not necessary
in actual markup.
|
<sect2 id="TOOPENANEXISTINGDOCUMENT">
<title>To Open an Existing Document</title>
<para>You can use Text Editor or File Manager to open an existing document.</para>
<IndexTerm><primary>document <secondary>opening</secondary>
</primary></IndexTerm>
<IndexTerm><primary>opening
<secondary>existing document</secondary>
</primary></IndexTerm>
<para>To open an existing document from the Text Editor:</para>
<OrderedList>
<ListItem>
<para> Choose Open from the File menu.</para>
<para> 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.</para>
</ListItem>
<ListItem>
<para> Select the document you want to open in the Files list or type the file name in the Open a File field. </para>
<para><emphasis>Or,</emphasis> 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.</para>
</ListItem>
<ListItem>
<para> Press Return or click OK.</para>
</ListItem>
</OrderedList>
<graphic id="some-graphic-id" entityref="some-graphic-entity"></graphic>
<para>To open an existing document from the File Manager:</para>
<IndexTerm><primary>opening
<secondary>document from File Manager</secondary>
</primary></IndexTerm>
<IndexTerm><primary>document
<secondary>opening from File Manager</secondary>
</primary></IndexTerm>
<IndexTerm><primary>File Manager
<secondary>opening documents</secondary>
</primary></IndexTerm>
<OrderedList>
<ListItem>
<para>Display the document's file icon in a File Manager Window.</para>
</ListItem>
<ListItem>
<para> Do one of the following: </para>
<InformalList>
<ListItem>
<para>Double-click the document's file icon.</para>
</ListItem>
<ListItem>
<para>Select the document, then choose Open from the Selected menu.</para>
</ListItem>
<ListItem>
<para>Drag the document to the Text Editor's control in the Front Panel.</para>
</ListItem>
</InformalList>
</ListItem>
</OrderedList>
<sect3>
<title>See Also</title>
<InformalList>
<ListItem>
<para><xref linkend="some-sect-id" endterm="some-sects-title-id"></para>
</ListItem>
<ListItem>
<para><xref linkend="another-sect-id" endterm="another-sects-title-id"></para>
</ListItem>
<ListItem>
<para><xref linkend="some-other-sect-id" endterm="some-other-sects-title-id"></para>
</ListItem>
</InformalList>
<sect3>
<sect2>
|
|
File
Entity Declarations |
|
To declare a file entity in formal markup, use this syntax:
<!entity entityname SYSTEM " filename"> |
Where entitynameis the name of the entity
and filename is the name of the file. The keyword
SYSTEM is required.
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">
|
Printable version
