Spelling fixes
[oweals/cde.git] / cde / doc / C / guides / helpGuide / ch07.sgm
1 <!-- $XConsortium: ch07.sgm /main/13 1996/09/08 19:40:15 rws $ -->
2 <!-- (c) Copyright 1995 Digital Equipment Corporation. -->
3 <!-- (c) Copyright 1995 Hewlett-Packard Company. -->
4 <!-- (c) Copyright 1995 International Business Machines Corp. -->
5 <!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
6 <!-- (c) Copyright 1995 Novell, Inc. -->
7 <!-- (c) Copyright 1995 FUJITSU LIMITED. -->
8 <!-- (c) Copyright 1995 Hitachi. -->
9 <chapter id="HRDC.Sgml.div.1">
10 <title id="HRDC.Sgml.mkr.1">Reading the DocBook Document Type Definition</title>
11 <para>This chapter explains how to read the DocBook 2.2.1 Document Type Definition
12 (DTD) and how to use it to create fully compliant Standard Generalized Markup
13 Language (SGML) help files.</para>
14 <informaltable id="HRDC.Sgml.itbl.1" frame="All">
15 <tgroup cols="1">
16 <colspec colname="1" colwidth="4.0 in">
17 <tbody>
18 <row rowsep="1">
19 <entry><para><!--Original XRef content: 'DocBook 1.3 DTD196'--><xref role="JumpText"
20 linkend="HRDC.Sgml.mkr.2"></para></entry></row>
21 <row rowsep="1">
22 <entry><para><!--Original XRef content: 'DTD Components196'--><xref role="JumpText"
23 linkend="HRDC.Sgml.mkr.3"></para></entry></row>
24 <row rowsep="1">
25 <entry><para><!--Original XRef content: 'Element Declarations196'--><xref
26 role="JumpText" linkend="HRDC.Sgml.mkr.4"></para></entry></row>
27 <row rowsep="1">
28 <entry><para><!--Original XRef content: 'Element Declaration Keywords198'--><xref
29 role="JumpText" linkend="HRDC.Sgml.mkr.5"></para></entry></row>
30 <row rowsep="1">
31 <entry><para><!--Original XRef content: 'Attribute List Declarations199'--><xref
32 role="JumpText" linkend="HRDC.Sgml.mkr.6"></para></entry></row>
33 <row rowsep="1">
34 <entry><para><!--Original XRef content: 'Formal Markup199'--><xref role="JumpText"
35 linkend="HRDC.Sgml.mkr.7"></para></entry></row></tbody></tgroup></informaltable>
36 <sect1 id="HRDC.Sgml.div.2">
37 <title>Document Type Definition</title>
38 <para>A <emphasis>Document Type Definition</emphasis> (DTD) defines a set
39 of elements used to create a structured (or hierarchical) document. The DTD
40 specifies the syntax for each element and governs how and where elements can
41 be used in a document.</para>
42 <sect2 id="HRDC.Sgml.div.3">
43 <title id="HRDC.Sgml.mkr.2">DocBook 2.1 DTD</title>
44 <para>The DocBook 2.2.1 DTD tag set and its associated rules are referred
45 to as formal markup. The DTD conforms to the Standard Generalized Markup Language
46 (SGML) ISO specification 8879:1986. This means that you can use formal markup
47 to create help files that are SGML compliant.</para>
48 <para>Appendix A contains the complete DTD specification. The DTD is also
49 available in the Developer's Toolkit. It is located in the <filename>/usr/dt/dthelp/dtdocbook/SGML</filename> directory and is named <filename>DocBook.dtd</filename>.</para>
50 <sect3 id="HRDC.Sgml.div.4">
51 <title>See Also</title>
52 <itemizedlist><listitem><para><filename>dtdocbookdtd(4)</filename> man page.
53 </para>
54 </listitem></itemizedlist>
55 </sect3>
56 </sect2>
57 </sect1>
58 <sect1 id="HRDC.Sgml.div.5">
59 <title id="HRDC.Sgml.mkr.3">DTD Components</title>
60 <para>The DTD defines each of the DocBook elements described in previous chapters
61 in a technical notation. This section introduces some key terms and explains
62 how to read the syntax of the element notations. It does not attempt to fully
63 describe each section of the DTD.</para>
64 <sect2 id="HRDC.Sgml.div.6">
65 <title id="HRDC.Sgml.mkr.4">Element Declarations</title>
66 <para>The DocBook DTD defines each DocBook element in an <emphasis>element
67 declaration</emphasis>. The declaration uses a precise notation to describe
68 an element, its required components, and any elements it can or cannot contain.
69 Each element also has its attributes and the values they can take defined
70 in an <emphasis>attribute declaration</emphasis>, which is discussed in the
71 next section <xref role="SecTitleAndPageNum" linkend="HRDC.Sgml.mkr.6">.</para>
72 <para>Both in its element declarations, and its attribute declarations, the
73 DocBook DTD makes extensive use of entity references, which stand for entities
74 that represent groupings of elements or attributes. (In the DTD, these entity
75 declarations precede the element declarations and the attribute declarations.)
76 </para>
77 <para>For example, the DTD declares an entity with the reference "%commmonatts;"
78 to stand for the group of common attributes that so many of the DocBook elements
79 have: ID, Lang (language), Remap, Role, and XRefLabel. As another example,
80 the DTD declares an entity with the reference "%list.gp;" that stands for
81 ItemizedList, OrderedList, SegmentedList, VariableList, etc.</para>
82 <para>The syntax of an element declaration is as follows:</para>
83 <programlisting>&lt;!ELEMENT <symbol>element_type minimization (content model)</symbol>></programlisting>
84 <para>Where:</para>
85 <informaltable>
86 <tgroup cols="2" colsep="0" rowsep="0">
87 <colspec align="left" colwidth="116*">
88 <colspec align="left" colwidth="412*">
89 <tbody>
90 <row>
91 <entry align="left" valign="top"><para><symbol>element_type</symbol></para></entry>
92 <entry align="left" valign="top"><para>Specifies the element name, which is
93 also used as the tag name. For example, the tag for the element type Title
94 is &lt;Title>.</para></entry></row>
95 <row>
96 <entry align="left" valign="top"><para><symbol>minimization</symbol></para></entry>
97 <entry align="left" valign="top"><para>A two-character entry that indicates
98 whether a start or an end tag is required. The first character represents
99 the start tag; the second character represents the end tag. A space separates
100 the two characters. The letter <Literal>O</Literal> means that the tag is
101 optional. A <literal>-</literal> (minus sign) indicates the tag is required.
102 </para><para>For example, an entry like this, <literal>- -</literal>, indicates
103 that the element requires both start and end tags. The DTD for DocBook 2.2.1
104 requires both start and end tags for the great majority of its elements.</para></entry>
105 </row>
106 <row>
107 <entry align="left" valign="top"><para><symbol>content model</symbol></para></entry>
108 <entry align="left" valign="top"><para>Specifies a list of the required and
109 optional elements that the element type can contain. It defines the sequence
110 of elements and, if applicable, the number of occurrences that may occur.
111 It also may specify the elements that cannot be contained within the element
112 in question.</para></entry></row></tbody></tgroup></informaltable>
113 <para>The content model uses these notations:</para>
114 <informaltable>
115 <tgroup cols="2" colsep="0" rowsep="0">
116 <colspec align="left" colwidth="106*">
117 <colspec align="left" colwidth="422*">
118 <tbody>
119 <row>
120 <entry align="left" valign="top"><para><literal>|</literal></para></entry>
121 <entry align="left" valign="top"><para>A vertical bar represents &ldquo;or&rdquo;.
122 </para></entry></row>
123 <row>
124 <entry align="left" valign="top"><para><literal>+</literal></para></entry>
125 <entry align="left" valign="top"><para>A plus sign after the name of the element
126 means the element must appear at least once, and that it can be repeated.
127 </para></entry></row>
128 <row>
129 <entry align="left" valign="top"><para><literal>*</literal></para></entry>
130 <entry align="left" valign="top"><para>An asterisk after the name of the element
131 means the element can appear zero or more times.</para></entry></row>
132 <row>
133 <entry align="left" valign="top"><para><literal>?</literal></para></entry>
134 <entry align="left" valign="top"><para>A question mark after the name of the
135 element means the element can appear zero or one time.</para></entry></row>
136 <row>
137 <entry align="left" valign="top"><para>,</para></entry>
138 <entry align="left" valign="top"><para>A comma describes sequence, that is,
139 the element type before the comma must be followed by the element specified
140 after the comma.</para></entry></row>
141 <row>
142 <entry align="left" valign="top"><para><literal>+</literal> (<symbol>element_
143 type(s)</symbol>)</para></entry>
144 <entry align="left" valign="top"><para>The <literal>+</literal> (plus sign)
145 indicates that the listed element or elements enclosed within the parentheses
146 can be used within the element type or within any of the elements it contains.
147 This is called an inclusion.</para></entry></row>
148 <row>
149 <entry align="left" valign="top"><para><literal>-</literal> (<symbol>element_
150 type(s)</symbol>)</para></entry>
151 <entry align="left" valign="top"><para>A <literal>-</literal> (minus sign)
152 indicates that the listed element or elements enclosed within the parentheses
153 cannot be used within this element, or within any of the elements it contains.
154 This is called an exclusion.</para></entry></row></tbody></tgroup></informaltable>
155 <sect3 id="HRDC.Sgml.div.7">
156 <title>Examples</title>
157 <para>Each of the following examples shows an element declaration and explains
158 what it means.</para>
159 <itemizedlist><listitem><para>This declares that the Appendix element requires
160 both starting and ending tags. It further declares that Appendix may contain
161 an optional DocInfo element, followed by a required Title, and an optional
162 TitleAbbrev, followed by one or more of the elements referred to by the entity
163 reference "%sect.gp;" (namely, Sect1 and its permitted subcomponents). It
164 also declares that the elements referred to by the entity reference "%ubiq.gp;"
165 (namely, IndexTerms) can be included within an Appendix or within any of its
166 subcomponents.</para>
167 <programlisting>&lt;:!ELEMENT Appendix - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;))  +(%ubiq.gp;) >
168 </programlisting>
169 </listitem><listitem><para>This declares that the OrderedList element requires
170 both starting and ending tags, and that it must contain at least one ListItem
171 </para>
172 <programlisting>&lt;!ELEMENT OrderedList - - (ListItem+) ></programlisting>
173 </listitem><listitem><para>This declares that the ListItem element requires
174 both starting and ending tags, and that it must contain at least one of the
175 group of elements referred to by the entity reference "%component.gp;", which
176 includes among other things Paragraphs, Lists, and Tables.</para>
177 <programlisting>&lt;!ELEMENT ListItem - - ((%component.gp;)+) ></programlisting>
178 </listitem><listitem><para>This declares that the Sect1 element requires both
179 starting and ending tags. It further declares that Sect1 has a required Title
180 and an optional TitleAbbrev. It next declares that Sect1 can have zero or
181 more ToCs, LoTs, Indexes, Glossaries, and Bibliographies (which are the elements
182 referred to by the entity reference "%nav.gp;"). It then declares that the
183 Sect1 element must contain at least one of the group of elements referred
184 to by the entity reference "%component.gp;", which includes among other things
185 Paragraphs, Lists,and Tables, and that these will optionally be followed by
186 zero or more Sect2s or RefEntries.</para>
187 <programlisting>&lt;!ELEMENT Sect1 - - (Title, TitleAbbrev?, (%nav.gp;)*, (((%component.gp;)+, (RefEntry* | Sect2*)) | RefEntry+ | Sect2+), (%nav.gp;)*)  +(%ubiq.gp;) >
188 </programlisting>
189 </listitem><listitem><para>This declares that the InformalTable element requires
190 both starting and ending tags. It further declares that InformalTable must
191 contain one or more Graphics or one or more TGroups (this is the meaning of
192 the string referred to by the entity reference "%tblcontent.gp;"). It also
193 declares that the InformalTable element cannot contain a Table or another
194 InformalTable.</para>
195 <programlisting>&lt;!ELEMENT InformalTable - - ((%tblcontent.gp;)) -(Table|InformalTable)>
196 </programlisting>
197 </listitem><listitem><para>This declares that the TGroup element requires
198 a start tag but not an end tag, and may contain the following elements in
199 the following order: zero or more ColSpecs, zero or more SpanSpecs, zero or
200 one THead, zero or one TFoot, and a required TBody.</para>
201 <programlisting>&lt;!ELEMENT TGroup - O (ColSpec*, SpanSpec*, THead?, TFoot?, TBody) >
202 </programlisting>
203 </listitem></itemizedlist>
204 </sect3>
205 </sect2>
206 <sect2 id="HRDC.Sgml.div.8">
207 <title id="HRDC.Sgml.mkr.5">Element Declaration Keywords</title>
208 <para>Some elements include a keyword in the element declaration that describes
209 the data content of the element. Three keywords appear in the DTD: <computeroutput>EMPTY</computeroutput>, <computeroutput>CDATA</computeroutput>, and <computeroutput>#PCDATA</computeroutput>.</para>
210 <informaltable>
211 <tgroup cols="2" colsep="0" rowsep="0">
212 <colspec align="left" colwidth="110*">
213 <colspec align="left" colwidth="418*">
214 <tbody>
215 <row>
216 <entry align="left" valign="top"><para><computeroutput>EMPTY</computeroutput></para></entry>
217 <entry align="left" valign="top"><para>Specifies that the element has no data
218 content.</para></entry></row>
219 <row>
220 <entry align="left" valign="top"><para><computeroutput>CDATA</computeroutput></para></entry>
221 <entry align="left" valign="top"><para>Represents &ldquo;character data.&rdquo;
222 That is, the data content of the element is not recognized as markup.</para></entry>
223 </row>
224 <row>
225 <entry align="left" valign="top"><para><computeroutput>#PCDATA</computeroutput></para></entry>
226 <entry align="left" valign="top"><para>Represents &ldquo;parsed character
227 data.&rdquo; That is, the data content may include both text and markup characters
228 that the DocBook parser interprets accordingly.</para></entry></row></tbody>
229 </tgroup></informaltable>
230 </sect2>
231 <sect2 id="HRDC.Sgml.div.9">
232 <title id="HRDC.Sgml.mkr.6">Attribute List Declarations</title>
233 <para>An attribute list declares additional properties that further describe
234 an element. An attribute list declaration has the syntax:</para>
235 <programlisting>&lt;!ATTLIST <symbol>element_type attribute_values default_value</symbol>></programlisting>
236 <sect3 id="HRDC.Sgml.div.7a">
237 <title>Examples</title>
238 <para>Each of the following examples shows an aatribute list declaration and
239 explains what it means.</para>
240 <itemizedlist><listitem><para>This attribute list declaration means that the
241 element Para has the common attributes, and there are no default values for
242 them.</para>
243 <programlisting>&lt;!ATTLIST Para       %commonatts;    ></programlisting>
244 </listitem><listitem><para>This attribute list declaration means that the
245 element Sect1 has the common attributes, and also a Label attribute and a
246 Renderas attribute. The Label attribute take "character data" for its values,
247 and the default value is implied. The Renderas attribute (which can determine
248 how the Sect1 is displayed) can take the values Sect2, Sect3, Sect4, or Sect5.
249 For example, if Renderas="Sect2", the Sect1 will be displayed with the same
250 formatting as a Sect2.</para>
251 <programlisting>&lt;!ATTLIST Sect1
252                 %commonatts;
253                 Label           CDATA           #IMPLIED
254                 Renderas        (Sect2 | Sect3 | Sect4 | Sect5)         #IMPLIED         ></programlisting>
255 </listitem><listitem><para>This attribute list declaration means that the
256 element TFoot has the common attributes, with no default values, and also
257 VAlign attribute which can take the values "Top", "Middle", and "Bottom",
258 with "Top" as the default value.</para>
259 <programlisting>&lt;!ATTLIST TFoot
260                 %commonatts;
261                 VAlign          (Top | Middle | Bottom) "Top"   ></programlisting>
262 </listitem><listitem><para>This attribute list declaration means that the
263 element OrderedList has the common attributes, with no default values, and
264 also several other attributes.</para>
265 <para>The Numeration attribute determines how the ListItems in the OrderedList
266 will be numbered: it takes the values "Arabic" (arabic numbers), "Upperalpha"
267 (capital letters), "Loweralpha" (lower case letters), "Upperroman" (upper
268 case Roman numerals) and "Lowerroman" (lower case Roman numerals).</para>
269 <para>The InheritNum attribute determines whether the numeration of an OrderedList
270 embedded in another OrderedList will be embedded in the numeration of the
271 containing list (so that the items in a list embedded in item 2 of another
272 list might be numbered 2a, 2b, 2c,etc.) InheritNum takes the values "Inherit"
273 and "Ignore", with "Ignore" as the default.</para>
274 <para>The Continuation attributes determines whether the numeration of an
275 OrderedList will continue from the numeration of the preceding OrderedList,
276 or start anew. It takes the values "Continues" and "Restarts", with "Restarts"
277 as the default.</para>
278 <programlisting>&lt;!ATTLIST OrderedList
279      %commonatts;
280      Numeration    (Arabic|Uperalpha|Loweralpha|Uperroman|Lowerroman)
281                                            #IMPLIED
282      InheritNum    (Inherit|Ignore)  Ignore
283      Continuation  (Continues|Restarts)   Restarts
284 ></programlisting>
285 </listitem></itemizedlist>
286 </sect3>
287 </sect2>
288 </sect1>
289 <sect1 id="HRDC.Sgml.div.10">
290 <title id="HRDC.Sgml.mkr.7">Formal Markup</title>
291 <para>After you have learned the basic set of elements, using a structured
292 editor is the best approach for creating formal markup. With a structured
293 editor, the author creates formal markup by choosing elements from a menu.
294 In response, the structured editor generates all of the tags required for
295 each element. In addition, it verifies that the structural framework being
296 created conforms to the Document Type Definition.</para>
297 <sect2 id="HRDC.Sgml.div.11">
298 <title id="HRDC.Sgml.mkr.8">Formal Markup Caveats</title>
299 <para>DocBook is a formal markup language. Nearly every element requires
300 a start and an end tag. If the start tag is <symbol>&lt;ElementName></symbol>,
301 the end tag will take the form <symbol>&lt;/ElementName></symbol>,with the
302 /(forward slash) marking it as the end tag.</para>
303 <para>In formal markup, each element, its component parts, and elements it
304 contains must be explicitly tagged. For example, here is a schematic formal
305 markup for a Row in a Table containing two Entries. (For ease of reading in
306 this and other markup examples, tags are indented. Indentation is not required
307 in actual markup.)</para>
308 <programlisting>&lt;row>
309         &lt;entry align="left" valign="top">
310                 &lt;para><symbol>contents of first entry</symbol>&lt;/para>
311         &lt;/entry>
312         &lt;entry align="left"valign="top">
313                 &lt;para><symbol>contents of second entry</symbol>&lt;/para>
314         &lt;/entry>
315 &lt;row>
316 </programlisting>
317 <para>Notice that Entry and Para, the subcomponents of the Row, each have
318 their own start and end tags.</para>
319 </sect2>
320 <sect2 id="HRDC.Sgml.div.13">
321 <title id="HRDC.Sgml.mkr.9">Explicit Hierarchy of Elements</title>
322 <para>Each element declaration in the DTD contributes to a set of rules that
323 governs how and where elements can be used. Because elements contain other
324 elements, which may contain other elements, a document is a hierarchy of
325 elements. At the top level, the Part element is the container for every other
326 element in the help volume.</para>
327 <para>To decide what markup is necessary to create a help topic, you need
328 to become familiar with the rules that govern the DocBook markup laguage.
329 </para>
330 <para>One way to learn the markup language would be to study the element declarations
331 for the components you need to use. For example, suppose you want to create
332 a chapter. First, look at the declaration for the Chapter element listed below.
333 </para>
334 <programlisting>&lt;!ELEMENT Chapter - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;), (Index |
335                 Glossary | Bibliography)*) +(%ubiq.gp;) ></programlisting>
336 <para>This tells you a Chapter may have a DocInfo component. So next you look
337 at the declaration for DocInfo, to see how it is constructed.</para>
338 <programlisting>&lt;!ELEMENT DocInfo - - (Title, TitleAbbrev?, Subtitle?, AuthorGroup+, Abstract*, RevHistory?, LegalNotice*) -(%ubiq.gp;) >
339 </programlisting>
340 <para>This tells you that a DocInfo requires at least a Title and one or more
341 AuthorGroups, and may optionally contain various other elements. So next
342 you would have check into the declarations for the Title element and the AuthorGroup
343 element, to see how they are constructed.</para>
344 <programlisting>&lt;!ELEMENT Title - - ((%inlinechar.gp;)+) >
345 &lt;!ELEMENT AuthorGroup - - ((Author | Editor | Collab | CorpAuthor |
346                 OtherCredit)+) >
347
348 </programlisting>
349 <para>By continuing along in this fashion until you have investigated all
350 the subcomponents of a Chapter, and all the subcomponents of the subcomponents,
351 down to the innermost nested element, and mastered how they work, you could
352 learn how to construct a Chapter.</para>
353 <para>Fortunately, however, using a structured editor minimizes what an author
354 needs to know about the DTD and the syntx of the markup tags. The structured
355 editor application &ldquo;reads&rdquo; the DTD and creates each element's
356 required tags, many of which are intermediate structural tags.</para>
357 <sect3 id="HRDC.Sgml.div.14">
358 <title>Example</title>
359 <para>This formal markup sample is an excerpt from the desktop Text Editor
360 help volume. To view the corresponding online information, choose the Help
361 Viewer in the Front Panel. Select Common Desktop Environment and then choose
362 Text Editor Help from the listed volumes. In the Text Editor volume, choose
363 Text Editor Tasks and then To Open an Existing Document.</para>
364 <para>Indentation and extra white space is used in this example to make it
365 easier to read the text and corresponding element tags. Remember that using
366 indentation and extra white space is not necessary in actual markup.</para>
367 <programlisting>&lt;sect2 id=&ldquo;TOOPENANEXISTINGDOCUMENT&rdquo;>
368         &lt;title>To Open an Existing Document&lt;/title>
369 &lt;para>You can use Text Editor or File Manager to open an existing document.&lt;/para>
370
371 &lt;IndexTerm>&lt;primary>document      &lt;secondary>opening&lt;/secondary>
372 &lt;/primary>&lt;/IndexTerm>
373
374 &lt;IndexTerm>&lt;primary>opening
375         &lt;secondary>existing document&lt;/secondary>
376 &lt;/primary>&lt;/IndexTerm>
377
378 &lt;para>To open an existing document from the Text Editor:&lt;/para>
379
380 &lt;OrderedList>
381 &lt;ListItem>
382         &lt;para> Choose Open from the File menu.&lt;/para>
383         &lt;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.&lt;/para>
384 &lt;/ListItem>
385
386 &lt;ListItem>
387         &lt;para> Select the document you want to open in the Files list or type the file name in the Open a File field. &lt;/para>
388         &lt;para>&lt;emphasis>Or,&lt;/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.&lt;/para>
389 &lt;/ListItem>
390
391 &lt;ListItem>
392         &lt;para> Press Return or click OK.&lt;/para>
393 &lt;/ListItem>
394
395 &lt;/OrderedList>
396
397 &lt;graphic id="some-graphic-id"        entityref="some-graphic-entity">&lt;/graphic>
398
399 &lt;para>To open an existing document from the File Manager:&lt;/para>
400
401 &lt;IndexTerm>&lt;primary>opening
402         &lt;secondary>document from File Manager&lt;/secondary>
403 &lt;/primary>&lt;/IndexTerm>
404
405 &lt;IndexTerm>&lt;primary>document
406         &lt;secondary>opening from File Manager&lt;/secondary>
407 &lt;/primary>&lt;/IndexTerm>
408
409 &lt;IndexTerm>&lt;primary>File Manager
410         &lt;secondary>opening documents&lt;/secondary>
411 &lt;/primary>&lt;/IndexTerm>
412
413 &lt;OrderedList>
414
415 &lt;ListItem>
416         &lt;para>Display the document's file icon in a File Manager Window.&lt;/para>
417 &lt;/ListItem>
418
419 &lt;ListItem>
420 &lt;para> Do <emphasis>one</emphasis> of the following: &lt;/para>
421 &lt;InformalList>
422
423 &lt;ListItem>
424 &lt;para>Double-click the document's file icon.&lt;/para>
425 &lt;/ListItem>
426
427 &lt;ListItem>
428 &lt;para>Select the document, then choose Open from the Selected menu.&lt;/para>
429 &lt;/ListItem>
430
431 &lt;ListItem>
432 &lt;para>Drag the document to the Text Editor's control in the Front Panel.&lt;/para>
433 &lt;/ListItem>
434
435 &lt;/InformalList>
436 &lt;/ListItem>
437
438 &lt;/OrderedList>
439
440 &lt;sect3>
441         &lt;title>See Also&lt;/title>
442
443 &lt;InformalList>
444
445 &lt;ListItem>
446         &lt;para>&lt;xref linkend="some-sect-id" endterm="some-sects-title-id">&lt;/para>
447 &lt;/ListItem>
448
449 &lt;ListItem>
450         &lt;para>&lt;xref linkend="another-sect-id" endterm="another-sects-title-id">&lt;/para>
451 &lt;/ListItem>
452
453 &lt;ListItem>
454         &lt;para>&lt;xref linkend="some-other-sect-id" endterm="some-other-sects-title-id">&lt;/para>
455 &lt;/ListItem>
456
457 &lt;/InformalList>
458
459 &lt;sect3>
460 &lt;sect2>
461
462 </programlisting>
463 </sect3>
464 </sect2>
465 <sect2 id="HRDC.Sgml.div.15">
466 <title id="HRDC.Sgml.mkr.10">File Entity Declarations</title>
467 <para>To declare a file entity in formal markup, use this syntax:</para>
468 <programlisting>&lt;!entity <symbol>entityname</symbol>  SYSTEM " <symbol>filename</symbol>"></programlisting>
469 <para>Where <symbol>entityname</symbol>is the name of the entity and <symbol>filename</symbol> is the name of the file. The keyword <computeroutput>SYSTEM</computeroutput> is required.</para>
470 <sect3 id="HRDC.Sgml.div.16">
471 <title>Example</title>
472 <para>Here are the entity declarations for a help volume that consists of
473 three text files and contains a graphic image.</para>
474 <programlisting>
475 &lt;!entity <symbol>MetaInformation</symbol> SYSTEM "<symbol>metainfo</symbol>">
476
477 &lt;!entity <symbol>BasicTasks</symbol> SYSTEM "<symbol>basics</symbol>">
478
479 &lt;!entity <symbol>AdvancedFeatures</symbol> SYSTEM "<symbol>advanced</symbol>">
480
481 &lt;!entity <symbol>process_diagram</symbol> SYSTEM "<symbol>process.tif</symbol>">
482
483 </programlisting>
484 </sect3>
485 </sect2>
486 </sect1>
487 </chapter>
488 <!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->