cde/doc/C/guides/helpGuide/ch02.sgm

   1 <!-- $XConsortium: ch02.sgm /main/16 1996/10/22 14:42:26 cdedoc $ -->
   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.OrgH.div.1">
  10 <title id="HRDC.OrgH.mkr.1">Organizing and Writing a Help Volume</title>
  11 <para>This chapter describes the organization and components of a help source
  12 file. It also provides a step-by-step example that shows how to process a
  13 help source file to create an online help volume.</para>
  14 <sect1 id="HRDC.OrgH.div.2">
  15 <title id="HRDC.OrgH.mkr.2">Help Volume Components</title>
  16 <para>A help volume has the following major types of components: entity declarations,
  17 a top-level volume topic (contained in the Part element) meta information
  18 (contained in the DocInfo element), book components (like Chapters, Sections,
  19 Lists, and Tables), the index and the glossary.</para>
  20 <sect2 id="HRDC.OrgH.div.3">
  21 <title>The Top Level Element: Part</title>
  22 <para>The <emphasis>Part</emphasis> is the top-level element in the structure
  23 of a help volume. All other components are subelements of Part in the structural
  24 hierarchy.</para>
  25 <para>The structural hierarchy under Part may be several levels deep with
  26 Chapters containing Sect1s, Sect1s containing Sect2s, Sect2s containing Sect3s,
  27 and so on. To help prevent users from getting lost, however, you should keep
  28 your hierarchy as shallow as possible.</para>
  29 <para>Part may contain the following components in the following order: an
  30 optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro,
  31 and one or more other book components, like Chapters.</para>
  32 <para>Part has the common attributes and a label attribute.</para>
  33 </sect2>
  34 <sect2 id="HRDC.OrgH.div.4">
  35 <title>Topics and Subtopics</title>
  36 <para>Topics and subtopics form a hierarchy below the Part. Typically, the
  37 first level of topics is divided into chapters, using the Chapter element.
  38 Within a chapter, topics are organized into sections, with subtopics of a
  39 Sect1 tagged as Sect2s, subtopics of a Sect2 tagged as Sect3s, and so on.
  40 </para>
  41 <para><xref role="CodeOrFigureOrTable" linkend="HRDC.OrgH.mkr.3"> shows a
  42 simple hierarchy that includes three chapters. Each chapter contains several
  43 first-level sections. The third chapter adds two second-level sections.</para>
  44 <figure>
  45 <title id="HRDC.OrgH.mkr.3">Help volume structural organization</title>
  46 <programlisting>Part
  47         DocInfo
  48         Title
  49         Chapter
  50                 Sect1
  51                 Sect1
  52                 Sect1
  53         Chapter
  54                 Sect1
  55                         Sect2
  56                                 Sect3
  57                         Sect2
  58                 Sect1
  59                 Sect1
  60                         Sect2
  61                         Sect2
  62                                 Sect3</programlisting>
  63 </figure>
  64 </sect2>
  65 <sect2 id="HRDC.OrgH.div.5">
  66 <title>Entities</title>
  67 <para>An author-defined <emphasis>entity</emphasis> can represent a string
  68 of characters or a file name. An <emphasis>entity declaration</emphasis> defines
  69 the entity name and the string or file it represents.</para>
  70 <para>Entities are useful for:</para>
  71 <itemizedlist><listitem><para><emphasis>Referencing a common string of text.</emphasis> This is useful if there is some likelihood that the text may change
  72 or you simply don't want to type it repeatedly. Each place you want the text
  73 inserted, you reference the entity name.</para>
  74 </listitem><listitem><para><emphasis>Referencing an external file.</emphasis>
  75 Entities are often used for accessing graphics files. The &lt;Graphic> element
  76 has an Entityref attribute, which refers to a graphic image file.</para>
  77 </listitem></itemizedlist>
  78 <para>All entity declarations must be entered before any other markup in your
  79 help volume. To include an entity that you have defined, you use an <emphasis>entity reference.</emphasis></para>
  80 <para>Entity references can be used anywhere within your help volume inside
  81 a document type declaration. When you process your help volume with the DocBook
  82 software, each entity reference is replaced with the text or file that the
  83 entity represents. <xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.22">describes
  84 how to define and use entities.</para>
  85 </sect2>
  86 <sect2 id="HRDC.OrgH.div.6">
  87 <title>Meta Information</title>
  88 <para><emphasis>Meta information</emphasis> is <emphasis>information about
  89 your information</emphasis>.</para>
  90 <para>In DocBook markup, meta information about a help volume is contained
  91 in the DocInfo element.</para>
  92 <para>DocInfo may contain the following elements in the following order:</para>
  93 <itemizedlist><listitem><para>Title (required)</para>
  94 </listitem><listitem><para>TitleAbbrev (optional)</para>
  95 </listitem><listitem><para>Subtitle (optional)</para>
  96 </listitem><listitem><para>one or more AuthorGroups (required)</para>
  97 </listitem><listitem><para>any number of Abstracts (optional brief descriptions
  98 of the volume's contents)</para>
  99 </listitem><listitem><para>a RevHistory (optional)</para>
 100 </listitem><listitem><para>any number of LegalNotices (optional, giving information
 101 on trademarks, copyrights, etc.)</para>
 102 </listitem></itemizedlist>
 103 <para>The Help System uses the meta information in DocInfo to display the
 104 Title of a help volume and its copyright information. The Abstract description
 105 is displayed by the desktop Help Viewer in the Front Panel. Other applications
 106 capable of displaying help volumes could also make use of this information.
 107 </para>
 108 <para><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.15"> shows you
 109 how to create a meta information section.</para>
 110 </sect2>
 111 <sect2 id="HRDC.OrgH.div.7">
 112 <title>Glossary</title>
 113 <para>The glossary includes definitions for important terms that you've used
 114 throughout your help volume. If a term is entered using the GlossTerm element,
 115 then it automatically becomes a link that, when selected, displays the glossary
 116 entry for that term.</para>
 117 </sect2>
 118 </sect1>
 119 <sect1 id="HRDC.OrgH.div.8">
 120 <title id="HRDC.OrgH.mkr.4">General Markup Guidelines</title>
 121 <para>Online help is written in ordinary text files. You use special codes,
 122 called <emphasis>tags</emphasis>, to markup <emphasis>elements</emphasis>
 123 within the information. The tags form a markup language called DocBook.</para>
 124 <para>If a standard text editor is used, DocBook markup is typed. If the editor
 125 provides a macro package, tags can be stored and inserted using command keys.
 126 DocBook markup can also be generated using a structured editor (see <xref
 127 role="SecTitleAndPageNum" linkend="HRDC.Intro.mkr.24">).</para>
 128 <para>The DocBook markup language defines a hierarchy of elements that define
 129 high-level elements, such as chapters and sections, block-oriented elements,
 130 such as paragraphs, lists, and tables, and low level in-line elements such
 131 as emphasized words and symbols.</para>
 132 <sect2 id="HRDC.OrgH.div.9">
 133 <title id="HRDC.OrgH.mkr.5">Markup in Your Source Files</title>
 134 <para>The markup for most elements consists of a start tag and an end tag.
 135 Start tags are entered with the element name between angle brackets (&lt;
 136 and >). End tags are similar, but the element name is preceded by a / (forward
 137 slash). Case is not significant in DocBook markup tags.</para>
 138 <programlisting>&lt;Element attribute name="attribute value"> ... text ... &lt;/Element>
 139 </programlisting>
 140 <para>For example, to mark the start and end of a book title you use markup
 141 like this:</para>
 142 <programlisting>&lt;Title id="GSNW">Geographical Survey of Northern Wisconsin&lt;/Title>
 143 </programlisting>
 144 <para>Where &lt;Title> is the start tag, and &lt;/Title> is the end tag, and
 145 GSNW is the value of the ID attribute of the Title element. If the element
 146 has more than one attribute with a specified value, the <symbol>attribute
 147 name</symbol>="<symbol>attribute value</symbol>" expressions are separated
 148 by spaces.</para>
 149 </sect2>
 150 </sect1>
 151 <sect1 id="HRDC.OrgH.div.13">
 152 <title id="HRDC.OrgH.mkr.7">A Help Volume at a Glance</title>
 153 <para>The following schematic markup illustrates important elements of a help
 154 volume and the tags used to enter them. Indentation is used here simply to
 155 highlight the hierarchical relationship of the elements; you don't need to
 156 indent the help files that you write.</para>
 157 <programlisting>DocType
 158 Part
 159         DocInfo
 160                 Title
 161                 AuthorGroup
 162                 Abstract
 163                 LegalNotice
 164         Title
 165         PartIntro
 166         Chapter
 167                 Title
 168                 Sect1
 169                         Title
 170                         Para
 171                         Para
 172                         Sect2
 173                                 Title
 174                                 Para
 175                                 Sect3
 176                                         Title
 177                                         Para
 178                                         Para
 179                         Sect2
 180                                 Title
 181                                 Para
 182         Chapter
 183                 Title
 184                 Sect1
 185                         Title
 186                         Para
 187                         Para
 188                         Sect2
 189                                 Title
 190                                 Para
 191                         Sect2
 192                                 Title
 193                                 Para
 194         Glossary
 195 </programlisting>
 196 </sect1>
 197 <sect1 id="HRDC.OrgH.div.14">
 198 <title id="HRDC.OrgH.mkr.8">Help Source Files</title>
 199 <para>Online help is written in ordinary text files. You process, or compile,
 200 these files with the DocBook software to create run-time help files that can
 201 be read by the Help System.</para>
 202 <sect2 id="HRDC.OrgH.div.15">
 203 <title>Creating Your volume.sgm File</title>
 204 <para>DocBook expects a primary control file named <symbol>volume</symbol><filename>.sgm</filename>, where <symbol role="Variable">volume</symbol> is a name you
 205 choose.</para>
 206 <para>Be sure your <symbol role="Variable">volume</symbol> name is unique
 207 and meaningful. If your <symbol role="Variable">volume</symbol> name is too
 208 general, it may conflict with another volume that someone else has created.
 209 If you are writing application help, one recommended practice is to use the
 210 application's class name.</para>
 211 <sect3 id="HRDC.OrgH.div.16">
 212 <title>Multiple Source Files</title>
 213 <para>The named <symbol>volume</symbol><filename>.sgm</filename> file contains
 214 entity declarations and entity references to files that make up the help volume.
 215 Although DocBook expects a single <symbol role="Variable">volume</symbol><filename>.sgm</filename> file as input, you can separate your work into multiple source
 216 files. Additional files are sourced into the <symbol role="Variable">volume</symbol><filename>.sgm</filename> file using <emphasis>file entities</emphasis>.
 217 A file entity is like a pointer to another file. That file, in effect, is
 218 inserted wherever the entity's name appears in the <symbol>volume</symbol><filename>.sgm</filename> file. The referenced files can also contain entity references
 219 to yet other files.</para>
 220 </sect3>
 221 <sect3 id="HRDC.OrgH.div.17">
 222 <title>Example</title>
 223 <para>Suppose a help volume has six chapters and each chapter is a separate
 224 file. The files are: HomeTopic, Metainfo, TOC, Tasks, Reference, and Glossary.
 225 The <symbol>volume</symbol><filename>.sgm</filename> file for the help volume
 226 includes file entities for each of the six files and a list of entity references
 227 that instruct the DocBook software to process the files.</para>
 228 <programlisting>...
 229 &lt;!entity HomeTopic        FILE &ldquo;HomeTopic&rdquo;>
 230 &lt;!entity MetaInformation  FILE &ldquo;Metainfo&rdquo;>
 231 &lt;!entity TableOfContents  FILE &ldquo;TOC&rdquo;>
 232 &lt;!entity Tasks            FILE &ldquo;Tasks&rdquo;>
 233 &lt;!entity Reference        FILE &ldquo;Reference&rdquo;>
 234 &lt;!entity Glossary         FILE &ldquo;Glossary&rdquo;>
 235 ...
 236 &amp;HomeTopic;
 237 &amp;MetaInformation;
 238 &amp;TableOfContents;
 239 &amp;Tasks;
 240 &amp;Reference;
 241 &amp;Glossary;
 242 </programlisting>
 243 <para>The details of running DocBook are covered in <xref role="SecTitleAndPageNum"
 244 linkend="HRDC.CrHV.mkr.3">.</para>
 245 </sect3>
 246 </sect2>
 247 </sect1>
 248 <sect1 id="HRDC.OrgH.div.18">
 249 <title id="HRDC.OrgH.mkr.9">Help Files in File Manager</title>
 250 <para>File Manager represents help files as file icons with a question mark.
 251 In <xref role="CodeOrFigureOrTable" linkend="HRDC.OrgH.mkr.10"> on <xref role="PageNum"
 252 linkend="HRDC.OrgH.mkr.10">, there is one source file (the one with the
 253 <filename>.sgm</filename>) and one run-time file (<filename>.sdl</filename> extension).
 254 If you double-click a markup file, your standard editor opens the file for
 255 editing. Double-clicking a (<filename>.sdl</filename> extension) file displays
 256 the run-time file using the Help Viewer.</para>
 257 <figure>
 258 <title id="HRDC.OrgH.mkr.10">File Manager view of help files</title>
 259 <graphic id="HRDC.OrgH.grph.2" entityref="HRDC.OrgH.fig.2"></graphic>
 260 </figure>
 261 <para>To create a run-time help volume, first select the <filename>.sgm</filename>
 262 file icon in File Manager. Then, choose Compile from the File Manager Selected
 263 menu.</para>
 264 <sect2 id="HRDC.OrgH.div.19">
 265 <title>See Also</title>
 266 <itemizedlist remap="Bullet1"><listitem><para><filename moreinfo="RefEntry">dthelpaction(4)</filename> man page</para>
 267 </listitem></itemizedlist>
 268 </sect2>
 269 </sect1>
 270 <sect1 id="HRDC.OrgH.div.20">
 271 <title id="HRDC.OrgH.mkr.11">Writing Your First Help Volume: A Step-by-Step
 272 Example</title>
 273 <para>Typically you organize your help files in a <filename>help</filename>
 274 directory. This step-by-step example demonstrates how to create and view a
 275 standalone help volume. (As a standalone volume, it does not involve interaction
 276 with an application.)</para>
 277 <para>To create and process a help volume, you follow these steps:</para>
 278 <orderedlist><listitem><para>Create the source directory for help files.</para>
 279 </listitem><listitem><para>Create the master DocBook file.</para>
 280 </listitem><listitem><para>Create the run-time help files.</para>
 281 </listitem><listitem><para>Display the help volume.</para>
 282 </listitem></orderedlist>
 283 <para>Each task is described in the section that follows. The markup language
 284 used in the text files is introduced later in this chapter. DocBook markup
 285 is described more fully in <xref role="ChapNumAndTitle" linkend="HRDC.WrTop.mkr.1">
 286 and in the <citetitle>Guide to the DocBook DTD</citetitle>.</para>
 287 <sect2 id="HRDC.OrgH.div.21">
 288 <title>Create the Source Directory</title>
 289 <orderedlist><listitem><para>Create a directory named <filename>helpfiles</filename> where you will create and process your help files.</para>
 290 </listitem><listitem><para>Create a text file named <filename>Commands.sgm</filename> in the directory just created.</para>
 291 <para>For this example, all the information is put into a single file. Typically,
 292 you will use multiple files to fully explain the system or application you
 293 are writing help for.</para>
 294 <para>The <filename>Commands.sgm</filename> file contains text and element
 295 tags. The element tags within the &lt; and > (angle brackets) indicate the
 296 structure of the information.</para>
 297 </listitem><listitem><para>Type the following markup text in the
 298 <filename>Commands.sgm</filename> file.</para>
 299 <programlisting>
 300 &lt;Chapter>
 301 &lt;Title id="CommandSummary-id>Command Summary&lt;/Title>
 302 &lt;Indexterm>&lt;Primary>commands&lt;Primary>&lt;/Indexterm>
 303 &lt;Para>Your&amp;product; is capable of the following operations:&lt;/Para>
 304 &lt;ItemizedList>
 305 &lt;ListItem>&lt;Para>&lt;Link Linkend="ChannelChange-id">ChannelChange&lt;/Link>&lt;/Para>&lt;/ListItem>
 306 &lt;ListItem>&lt;Para>&lt;Link Linkend="VolumeUp-id"> VolumeUp &lt;/Link>       &lt;/Para>&lt;/ListItem>
 307 &lt;ListItem>&lt;Para>&lt;Link Linkend="VolumeDown-id"> VolumeDown &lt;/Link>&lt;/Para>&lt;/ListItem>
 308 &lt;ListItem>&lt;Para>&lt;Link Linkend="VolumeMute-id"> VolumeMute &lt;/Link>&lt;/Para>&lt;/ListItem>
 309 &lt;/ItemizedList>
 310 &lt;Para>Choose one of the hyperlinks (underlined phrases)
 311 to find out how to perform that operation.&lt;/Para>
 312 &lt;Sect1 id="ChannelChange-s">
 313 &lt;Title id="ChannelChange-t">Changing the Channel&lt;/Title>
 314 &lt;Indexterm>&lt;Primary>channel&lt;Secondary>changing&lt;/Secondary>&lt;Primary>&lt;/Indexterm>
 315 &lt;Para>Speak the command:
 316 &lt;Programlisting> channel&lt;/Programlisting>
 317 followed by a number from &lt;Command>one&lt;/Command>to &lt;Command>ninety-nine&lt;/Command>.&lt;/Para>
 318 &lt;/Sect1>
 319 &lt;Sect1 id="VolumeUp-s">
 320 &lt;Title id="VolumeUp-t">Turning Up the Volume&lt;/Title>
 321 &lt;Indexterm>&lt;Primary>volume&lt;Secondary>changing&lt;/Secondary>&lt;/Primary>&lt;/Indexterm>
 322 &lt;Para>Speak the command:
 323 &lt;Programlisting>volume up&lt;/Programlisting>&lt;/Para>
 324 &lt;Para>For additional volume, speak the command:
 325 &lt;Programlisting>more&lt;/Programlisting>&lt;/para>
 326 &lt;Para>(See also &lt;Link Linkend="VolumeDown-id">VolumeDown&lt;/Link>)&lt;/Para>
 327 &lt;/Sect1>
 328 &lt;Sect1 id="VolumeDown-s">
 329 &lt;Title id="VolumeDown-t">Turning Down the Volume&lt;/Title>
 330 &lt;Indexterm>&lt;Primary>volume&lt;Secondary>changing&lt;/Secondary>&lt;/Primary>&lt;/Indexterm>
 331 &lt;Para>Speak the command:
 332 &lt;Programlisting>volume down&lt;/Programlisting>&lt;/Para>
 333 &lt;Para>To reduce the volume further, speak the command:
 334 &lt;Programlisting>more&lt;/Programlisting>&lt;/Para>
 335 &lt;Para>(See also &lt;Link Linkend="VolumeUp-id"> VolumeUp &lt;/Link> and &lt;Link Linkend="VolumeMute-id">VolumeMute&lt;/Link>)&lt;/Para>
 336 &lt;/Sect1>
 337 &lt;Sect1 id="VolumeMute-s">
 338 &lt;Title id="VolumeMute-t">Turning Off the Sound&lt;/Title>
 339 &lt;Indexterm>&lt;Primary>volume&lt;Secondary>changing&lt;/Secondary>&lt;/Primary>&lt;/Indexterm>
 340 &lt;Indexterm>&lt;Primary>sound&lt;Secondary>on/off&lt;/Secondary>&lt;/Primary>&lt;/Indexterm>
 341 &lt;Para>Speak the command:
 342 &lt;Programlisting>sound off&lt;/Programlisting>&lt;/Para>
 343 &lt;Para>To restore the sound, speak the command:
 344 &lt;Programlisting>sound on&lt;/Programlisting>&lt;/Para>
 345 &lt;Para>(See also &lt;Link Linkend="VolumeDown-id">VolumeDown&lt;/Link> and &lt;Link Linkend="VolumeUp-id">VolumeUp&lt;/Link>&lt;/Para>
 346 &lt;/Sect1>
 347 &lt;/Chapter>
 348 </programlisting>
 349 </listitem><listitem><para>Create a text file that gives the information a
 350 title, provides copyright information, and provides other information about
 351 the online help.</para>
 352 <para>In this example, the following text is put into a file called
 353 <filename>Metainfo.sgm</filename> in the same directory as the <filename>Commands.sgm</filename>file.</para>
 354 <programlisting>&lt;DocInfo>
 355  &lt;Title> Using the &amp;product;&lt;/Title>
 356         &lt;AuthorGroup>&lt;Author>Jim Jonas&lt;/Author>
 357                 &lt;/AuthorGroup>
 358         &lt;Abstract> Help for Using the &amp;product;.
 359                 &lt;/Abstract>
 360         &lt;LegalNotice>
 361         &lt;BlockQuote>
 362         &lt;para>&amp;copy; 1995 Voice Activation Company.
 363         All rights reserved.&lt;/para>
 364         &lt;/BlockQuote>
 365                 &lt;/LegalNotice>
 366 &lt;/DocInfo>
 367 </programlisting>
 368 </listitem></orderedlist>
 369 </sect2>
 370 <sect2 id="HRDC.OrgH.div.23">
 371 <title>Create the Master DocBook File</title>
 372 <orderedlist><listitem><para>Create a text file whose name is of the form <symbol role="Variable">volume</symbol><filename>.sgm</filename>. In this example,
 373 the file is named <filename>voiceact.sgm</filename>.</para>
 374 </listitem><listitem><para>In the <filename>voiceact.sgm</filename> file,
 375 define <emphasis>entities</emphasis> that associate the names of the
 376 <filename>Commands.sgm</filename> and <filename>Metainfo.sgm</filename> files with entity
 377 names. Also, define any entities that are used (either directly or indirectly)
 378 in the <filename>Commands.sgm</filename> and <filename>Metainfo.sgm</filename>
 379 files. Finally, refer to the <filename>Commands.sgm</filename> and
 380 <filename>Metainfo.sgm</filename> files by their entity names.</para>
 381 </listitem></orderedlist>
 382 <para>In this example, the contents of the <filename>voiceact.sgm</filename>
 383 file look like this. The text within the <literal>&lt;!--&hellip;--></literal>
 384 elements are comments, which are ignored.</para>
 385 <programlisting>&lt;!-- Declare an entity for each of the source text files. -->
 386 &lt;!entity MetaInformation  FILE &ldquo;Metainfo&rdquo;>
 387 &lt;!entity Commands   FILE &ldquo;Commands&rdquo;>
 388
 389 &lt;!-- Define an entity that names the product and includes
 390         the trademark symbol (&amp;tm;). -->
 391
 392 &lt;!entity product &ldquo;VoAc&amp;tm; Voice-Activated Remote Control&rdquo;>
 393
 394 &lt;!-- Include the text files. -->
 395 &lt;Part>
 396 &amp;MetaInformation;
 397 &amp;Commands;
 398 &lt;/Part></programlisting>
 399 </sect2>
 400 <sect2 id="hrdc.orgh.div.25">
 401 <title>Create the Run-Time Help Files</title>
 402 <orderedlist><listitem><para>Verify that the <filename>/usr/dt/bin</filename>
 403 directory is in your search path by typing this command in a terminal window:
 404 </para>
 405 <para><command>echo $PATH</command></para>
 406 <para>If the directory is not in your path, add it to your PATH environment
 407 variable. If you're not sure how to do this, refer to your system documentation
 408 or ask your system administrator.</para>
 409 </listitem><listitem><para>Open File Manager and change to the
 410 <filename>helpfiles</filename> directory. Select the <filename>voiceact.sgm</filename>
 411 file icon and choose Compile from the Selected menu in File Manager.</para>
 412 <para>This executes the DocBook software which creates a run-time version
 413 of your online help volume (<filename>voiceact.sdl</filename>). Status and
 414 error messages are placed in a new file, whose name is of the form <symbol>volume</symbol><filename>.log</filename>.</para>
 415 </listitem><listitem><para>Open the <filename>voiceact.log</filename> file
 416 to check that your file processed without errors. If errors occurred, fix
 417 them by editing or renaming the text files as needed.</para>
 418 </listitem></orderedlist>
 419 <note>
 420 <para>You can run DocBook manually in a terminal window.</para>
 421 <para>To do so, execute the following command:</para>
 422 <para><command>dtdocbook voiceact.sgm</command></para>
 423 </note>
 424 </sect2>
 425 <sect2 id="hrdc.orgh.div.26">
 426 <title>Display the Help Volume</title>
 427 <para>From the <filename>helpfiles</filename> directory, double-click the
 428 <filename>voiceact.sdl</filename> file icon.</para>
 429 <para>This displays the help volume using the desktop Help Viewer. You can
 430 now scroll through the information and jump to related information by choosing
 431 hyperlinks.</para>
 432 <note>
 433 <para>You can run the Help Viewer manually in a terminal window.</para>
 434 <para>To do so, execute the following command, which displays the new help
 435 volume:</para>
 436 <para><command>dthelpview -h voiceact.sdl</command></para>
 437 </note>
 438 <sect3 id="hrdc.orgh.div.27">
 439 <title>See Also</title>
 440 <itemizedlist><listitem><para><xref role="ChapNumAndTitle" linkend="hrdc.crhv.mkr.1">,
 441 on <xref role="PageNum" linkend="hrdc.crhv.mkr.1"></para>
 442 </listitem><listitem><para><xref role="ChapNumAndTitle" linkend="hrdc.cmds.mkr.1">,
 443 on <xref role="PageNum" linkend="hrdc.cmds.mkr.1"></para>
 444 </listitem></itemizedlist>
 445 </sect3>
 446 </sect2>
 447 </sect1>
 448 <sect1 id="HRDC.OrgH.div.28">
 449 <title id="HRDC.OrgH.mkr.12">Creating a Topic Hierarchy</title>
 450 <para>The topic hierarchy within your help volume begins with the <emphasis>Part</emphasis>. Each help volume must have one Part. The first level of subtopics
 451 below Part must be entered with &lt;Chapter> tags.</para>
 452 <para>Additional levels of subtopics are entered with &lt;Sect1>, &lt;Sect2>,
 453 &lt;Sect3>, &lt;Sect4>, and &lt;Sect5>. The DocBook markup language supports
 454 five topic levels, but bear in mind that information more than three or four
 455 levels deep often leads many readers to feel lost.</para>
 456 <para>When a help volume is displayed, the help window displays a list of
 457 topics in its topic tree. Any topic entered with a &lt;Chapter>, &lt;Sect1>,
 458 &lt;Sect2>, &lt;Sect3>, &lt;Sect4>, or &lt;Sect5> tag automatically appears
 459 in the topic tree. This provides an easy way to browse and view topics.</para>
 460 <para>To enable users to display other related information from within a topic,
 461 you create hyperlinks. To do so, you assign a unique ID to each destination
 462 topic. Hyperlinks make it possible to reference a specific ID anywhere in
 463 your help information.</para>
 464 <sect2 id="HRDC.OrgH.div.29">
 465 <title>Example</title>
 466 <para>Suppose you want to create a hierarchy to match this simple outline:
 467 </para>
 468 <programlisting>Tutorial for New Users
 469         Module 1: Getting Started
 470         Module 2: Creating Your First Report
 471         Module 3: Printing the Report
 472         Module 4: Saving Your Work and Quitting
 473 Task Reference
 474         Starting and Stopping
 475                 To Start the Program
 476                 To Quit the Program
 477         Creating Reports
 478                 To Create a Detailed Report
 479                 To Create a Summary Report
 480 Concepts for Advanced Users
 481         Using Report Hot Links
 482         Sharing Reports within a Workgroup
 483 Reference
 484         Command Summary
 485         Report Attributes Summary</programlisting>
 486 <para>Then the general outline of your help volume would look like this.</para>
 487 <programlisting>&lt;Part>
 488 &lt;title>Welcome to ReportMaster&lt;/title>
 489
 490 &lt;chapter>
 491         &lt;title>Tutorial for New Users&lt;/title>
 492         overview of chapter topic
 493         &lt;sect1>
 494         &lt;title>Module 1: Getting Started&lt;/title>
 495                 body of topic
 496                 &lt;/sect1>
 497         &lt;sect1>
 498         &lt;title>Module 2: Creating Your First Report&lt;/title>
 499                 body of topic
 500                 &lt;/sect1>
 501         &lt;sect1>
 502         &lt;title>Module 3: Printing the Report&lt;/title>
 503                 body of topic
 504                 &lt;/sect1>
 505         &lt;sect1>
 506         &lt;title>Module 4: Saving Your Work and Quitting&lt;/title>
 507                 body of topic
 508                 &lt;/sect1>
 509 &lt;/chapter>
 510
 511 &lt;chapter>
 512         &lt;title>Task Reference&lt;/title>
 513         overview of chapter topic
 514 &lt;sect1>
 515         &lt;title>Starting and Stopping&lt;/title>
 516         body of topic
 517         &lt;sect2>
 518                 &lt;title>To Start the Program&lt;/title>
 519                 body of topic
 520                 &lt;/sect2>
 521         &lt;sect2>
 522                 &lt;title>To Quit the Program&lt;/title>
 523                 body of topic
 524                 &lt;/sect2>
 525 &lt;sect1>
 526         &lt;title>Creating Reports&lt;/title>
 527         body of topic
 528         &lt;sect2>
 529                 &lt;title>To Create a Detailed Report&lt;/title>
 530                 body of topic
 531                 &lt;/sect2>
 532         &lt;sect2>
 533                 &lt;title>To Create a Summary Report&lt;/title>
 534                 body of topic
 535                 &lt;/sect2>
 536         &lt;/sect1>
 537 &lt;/chapter>
 538
 539 &lt;chapter>
 540         &lt;title>Concepts for Advanced Users&lt;/title>
 541         overview of chapter topic
 542         &lt;sect1>
 543         &lt;title>Using Report Hot Links&lt;/title>
 544                 body of topic
 545                 &lt;/sect1>
 546         &lt;sect1>
 547         &lt;title>Sharing Reports within a Workgroup&lt;/title>
 548                 body of topic
 549                 &lt;/sect1>
 550 &lt;/chapter>
 551
 552 &lt;chapter>
 553         &lt;title>Reference&lt;/title>
 554         overview of chapter topic
 555         &lt;sect1>
 556         &lt;title>Command Summary&lt;/title>
 557                 body of topic
 558                 &lt;/sect1>
 559         &lt;sect1>
 560         &lt;title>Report Attributes Summary&lt;/title>
 561                 body of topic
 562                 &lt;/sect1>
 563 &lt;/chapter>
 564 &lt;/part></programlisting>
 565 <para>(The body of each topic and IDs for the topics are not shown. Spacing
 566 and indentations are only for ease of reading, and are not significant.)</para>
 567 <sect3 id="HRDC.OrgH.div.30">
 568 <title>See Also</title>
 569 <itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.18">describes
 570 assigning IDs to topics</para>
 571 </listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.WrTop.mkr.14">describes
 572 how to create hyperlinks</para>
 573 </listitem></itemizedlist>
 574 </sect3>
 575 </sect2>
 576 <sect2 id="hrdc.orgh.div.31" role="Procedure">
 577 <title id="hrdc.orgh.mkr.13">To Create a Part</title>
 578 <itemizedlist><listitem><para>Use the Part element as follows:</para>
 579 </listitem></itemizedlist>
 580 <programlisting>&lt;Part>
 581         &lt;DocInfo>
 582                 &lt;Title>Volume Title&lt;/Title>
 583                 &lt;AuthorGroup>
 584                         &lt;Author>author's name here&lt;/Author>
 585                 &lt;/AuthorGroup>
 586                 &lt;Abstract>
 587                         &lt;Para>abstract here&lt;/Para>
 588                 &lt;/Abstract>
 589                 &lt;LegalNotice>
 590                         &lt;BlockQuote>
 591                         &lt;Para>copyrights etc. &lt;/Para>
 592                         &lt;/BlockQuote>
 593                 &lt;/LegalNotice>
 594         &lt;/DocInfo>
 595         &lt;Title>Volume Title&lt;/Title>
 596         &lt;/PartIntro>&lt;Para>This is the home topic.&lt;/Para>&lt;/PartIntro>
 597         &lt;Chapter Id="chapid">
 598                 &lt;Title>This Chapter&lt;/Title>
 599                 &lt;Sect1 Id="sect1id">
 600                         &lt;Title>Sect1 Heading&lt;/Title>
 601                         &lt;Sect2 Id="sect2id">
 602                                 &lt;Title>Sect2 Heading&lt;/Title>
 603                 ...
 604                 ...
 605                 ...
 606                         &lt;/sect2>
 607                 &lt;/sect1>
 608         &lt;/chapter>
 609 &lt;/Part>
 610 </programlisting>
 611 <para>Part may contain the following components in the following order: an
 612 optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro,
 613 and one or more other book components, like Chapters and Sections.</para>
 614 <para>Note that the Title of the help volume appears twice, if a DocInfo is
 615 present: once within DocInfo, and again as the first element following DocInfo.
 616 </para>
 617 <sect3 id="hrdc.orgh.div.32">
 618 <title>Example</title>
 619 <para>Here's a sample Part with a PartIntro that includes hyperlinks to the
 620 Part's four subtopics:</para>
 621 <programlisting>
 622 &lt;/Part>
 623 &lt;title>Report Master&lt;/title>
 624 &lt;PartIntro>
 625 &lt;Para>Welcome to the online help for Report Master. Please choose one of the following hyperlinks:&lt;/Para>
 626 &lt;itemizedlist>
 627 &lt;listitem>&lt;para>&lt;Link Linkend="Tutorial-id">Tutorial&lt;/Link> &lt;/para>&lt;/listitem>
 628 &lt;listitem>&lt;para>&lt;Link Linkend="Tasks-id">Tasks&lt;/Link>&lt;/para>&lt;/listitem>
 629         &lt;listitem>&lt;para>&lt;Link Linkend="Concepts-id">VolumeDown&lt;/Link>&lt;/para>&lt;/listitem>
 630         &lt;listitem>&lt;para>&lt;Link Linkend="Reference-id">VolumeMute&lt;/Link>&lt;/para>&lt;/listitem>
 631 &lt;/itemizedlist>.
 632 &lt;Para>If you need help, press F1.&lt;/Para>
 633 &lt;/PartIntro>
 634 ...
 635 &lt;/Part></programlisting>
 636 <para>The preceding markup produces this output:</para>
 637 <graphic id="hrdc.orgh.igrph.2" entityref="HRDC.OrgH.fig.4"></graphic>
 638 </sect3>
 639 </sect2>
 640 <sect2 id="hrdc.orgh.div.33" role="Procedure">
 641 <title id="hrdc.orgh.mkr.14">To Add a Topic to the Hierarchy</title>
 642 <itemizedlist><listitem><para>To add another topic at the same level, close
 643 the element using its end tag, then repeat the same element by opening it
 644 with its start tag.</para>
 645 <para>To add a subtopic (a topic one level deeper in the hierarchy), use the
 646 element that is one level deeper than the preceding topic.</para>
 647 </listitem></itemizedlist>
 648 <sect3 id="hrdc.orgh.div.34">
 649 <title>Example</title>
 650 <para>If the current topic is a &lt;Sect1>, enter a subtopic using &lt;Sect2>.
 651 </para>
 652 <programlisting>&lt;sect1>
 653         &lt;title>Creating Reports&lt;/title>
 654         body of the topic
 655         &lt;sect2>
 656                 &lt;title>To Create a Detailed Report&lt;/title>
 657                 body of the first subtopic
 658                 &lt;/sect2>
 659         &lt;sect2>
 660                 &lt;title>To Create a Summary Report&lt;/title>
 661                 body of the second subtopic
 662                 &lt;/sect2>
 663 &lt;/sect1></programlisting>
 664 <para>The second Sect2 is also a subtopic of the Sect1.</para>
 665 <note>
 666 <para>Sometimes parent-child-sibling metaphors are used to describe the relationships
 667 topics in a hierarchy. In the preceding example, the Sect1 topic is the &ldquo;parent&rdquo;
 668 of both Sect2s (the &ldquo;children&rdquo; topics). The two Sect2s are &ldquo;siblings&rdquo;
 669 of one another. All three topics are &ldquo;descendents&rdquo; of the Chapter's
 670 topic.</para>
 671 </note>
 672 </sect3>
 673 </sect2>
 674 </sect1>
 675 <sect1 id="HRDC.OrgH.div.35">
 676 <title id="HRDC.OrgH.mkr.15">Creating Meta Information Topics</title>
 677 <para>The DocInfo meta information section is primarily intended for <emphasis>information about information</emphasis>. In the DocBook markup language,
 678 Meta information for a help volume is contained in the DocInfo element that
 679 may occur as the first component of a Part. DocInfo contains information about
 680 the help volume's title and authors, may contain legal notices about copyrights
 681 and trademarks, and abstracts of the volume's contents.</para>
 682 <para>DocInfo may contain the following elements in the following order:</para>
 683 <itemizedlist><listitem><para>Title (required)</para>
 684 </listitem><listitem><para>TitleAbbrev (optional)</para>
 685 </listitem><listitem><para>Subtitle (optional)</para>
 686 </listitem><listitem><para>one or more AuthorGroups (required)</para>
 687 </listitem><listitem><para>any number of Abstracts (optional)</para>
 688 </listitem><listitem><para>a RevHistory (optional)</para>
 689 </listitem><listitem><para>any number of LegalNotices (optional)</para>
 690 </listitem></itemizedlist>
 691 <sect2 id="HRDC.OrgH.div.36" role="Procedure">
 692 <title id="HRDC.OrgH.mkr.16">To Create a Meta Information Section</title>
 693 <orderedlist><listitem><para>Enter the &lt;DocInfo> tag to start the section,
 694 and follow immediately with the required Title element, as shown:</para>
 695 <programlisting>&lt;DocInfo>
 696         &lt;title><symbol>Volume Title Here</symbol>&lt;/title>
 697 </programlisting>
 698 </listitem><listitem><para>Enter the optional TitleAbbrev and Subtitle elements
 699 if needed.</para>
 700 </listitem><listitem><para>Enter the required AuthorGroup element, which contains
 701 one or more Authors, Collabs, or CorpAuthors, in any order.</para>
 702 </listitem><listitem><para>Enter the optional Abstract and LegalNotice elements
 703 if needed, following these syntax models:</para>
 704 <programlisting>&lt;Abstract Id="SDL-RESERVED-abstract">
 705         &lt;Para>abstract here&lt;/Para>
 706 &lt;/Abstract>
 707
 708 &lt;LegalNotice Id="SDL-RESERVED-copyright">
 709         &lt;BlockQuote>
 710                 &lt;Para>&copy; year &amp; copyright holder's name&lt;/Para>
 711         &lt;/BlockQuote>
 712 &lt;/LegalNotice>
 713 </programlisting>
 714 </listitem><listitem><para>Enter the DocInfo end tag to end the section.</para>
 715 </listitem></orderedlist>
 716 <para>The Abstract section is recommended. Applications that access help volumes
 717 can use this information to present a brief description of the volume. Because
 718 the abstract might be displayed in plain text windows avoid including any
 719 DocBook markup in the abstract.</para>
 720 <sect3 id="HRDC.OrgH.div.37">
 721 <title>Example</title>
 722 <para>Here's a markup for typical meta information section contained in the
 723 DocInfo element:</para>
 724 <programlisting>
 725 &lt;DocInfo>
 726 &lt;title>Report Master, Version 1.0&lt;/title>
 727
 728 &lt;AuthorGroup>
 729         &lt;Author>Jim Jonas&lt;/Author>
 730 &lt;/AuthorGroup>
 731
 732 &lt;Abstract>
 733         &lt;Para>This is the online help for the mythical Report Master application. This help includes a self-guided tutorial, a summary of common tasks, general concepts, and quick reference summaries.&lt;/Para>
 734 &lt;/Abstract>
 735
 736 &lt;LegalNotice>
 737         &lt;BlockQuote>
 738                 &lt;Para>
 739         Version 1.0
 740         &amp;copy; Copyright Reports Incorporated 1995
 741         All rights reserved.
 742                 &lt;/Para>
 743         &lt;/BlockQuote>
 744 &lt;/LegalNotice>
 745 &lt;/DocInfo></programlisting>
 746 <para>The BlockQuote element is used to preserve the line breaks in the copyright
 747 notice. The <literal>&amp;copy;</literal> entity inserts the copyright symbol.
 748 </para>
 749 </sect3>
 750 </sect2>
 751 </sect1>
 752 <sect1 id="HRDC.OrgH.div.39">
 753 <title>Adding a Nonhierarchical Topic</title>
 754 <para>Topics entered with the Chapter, Sect1, Sect2, Sect3, Sect4, Sect5 element
 755 tags automatically appear in the topic tree. When a title is selected in the
 756 topic tree, the corresponding help topic is displayed in a general help dialog
 757 box.</para>
 758 <para>Sometimes you may want to create and display a topic independent of
 759 the structural hierarchy you have created. These nonhierarchical topics are
 760 useful for creating custom definition links that pop-up a topic in a quick
 761 help dialog box.</para>
 762 <para>Appendix is the tag for a free-floating heading not tied to the Sect
 763 hierarchy. It may contain inline elements.</para>
 764 <para>Appendix has the common attributes, including the ID attribute and the
 765 XRefLabel atttribute, and also the Label attribute. When using the Appendix
 766 element for nonhierarchical topics, the value of the Role attribute should
 767 be &ldquo;notoc&rdquo;.</para>
 768 <sect2 id="hrdc.orgh.div.40" role="Procedure">
 769 <title id="hrdc.orgh.mkr.17">To Add a Nonhierarchical Topic</title>
 770 <itemizedlist><listitem><para>Add the nonhierarchical topic using the BridgeHead
 771 element as follows:</para>
 772 <programlisting>&lt;Appendix id="bh-some-id" role="notoc">
 773         <symbol>text of the topic</symbol>
 774 &lt;/Appendix></programlisting>
 775 </listitem></itemizedlist>
 776 <para>Presumably, a definition link to display this topic will exist within
 777 some other topic in the help volume.</para>
 778 <para>The link might look like this:</para>
 779 <programlisting>Here's a sample of a pop-up &lt;link linkend="bh-some-id">
 780 definition link.&lt;/link></programlisting>
 781 <para>The words &ldquo;definition link&rdquo; become the active hyperlink
 782 and will be displayed with a dashed underline. Selecting the link displays
 783 the text of the topic in a quick help dialog box.</para>
 784 <sect3 id="hrdc.orgh.div.42">
 785 <title>See Also</title>
 786 <itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="hrdc.wrtop.mkr.14"></para>
 787 </listitem></itemizedlist>
 788 </sect3>
 789 </sect2>
 790 </sect1>
 791 <sect1 id="HRDC.OrgH.div.43">
 792 <title id="HRDC.OrgH.mkr.18">Accessing Topics</title>
 793 <para>Many elements in the DocBook language support an ID attribute. An ID
 794 is a unique name used internally to identify topics and elements within topics.
 795 Since ID is one of DocBook's common attributes, any element with the common
 796 attributes can support an ID attribute.</para>
 797 <para>An ID is defined only once, but multiple hyperlinks and cross-references
 798 can refer to the same ID. IDs are not seen by the user.</para>
 799 <para>If you are writing help for an application, IDs are also used by the
 800 application to identify particular topics to display when the user requests
 801 help.</para>
 802 <para>For example, you might write several topics that describe an application's
 803 menus. The IDs that you assign to the topics are used by the application developer.
 804 By defining identical IDs within the application code, the developer can integrate
 805 specific topics. This allows the application to access and display the correct
 806 topic when help is requested for a particular menu.</para>
 807 <sect2 id="HRDC.OrgH.div.44">
 808 <title>Rules for ID Names</title>
 809 <itemizedlist><listitem><para>ID strings may contain letters (A - Z and a
 810 - z), digits (0 - 9), the period (.), and the minus (&minus;) sign. ID strings
 811 must begin with a letter, and be unique at least within the document in which
 812 they occur.</para>
 813 </listitem><listitem><para>Case in ID strings is <emphasis>not</emphasis>
 814 significant, but is often used to increase readability.</para>
 815 </listitem><listitem><para>ID strings cannot be longer than 128 characters.
 816 </para>
 817 </listitem><listitem><para>Each ID within a single help volume must be unique.
 818 </para>
 819 </listitem></itemizedlist>
 820 </sect2>
 821 <sect2 id="HRDC.OrgH.div.44a">
 822 <title>Built-in IDs</title>
 823 <para>A few elements have built-in IDs, and so do not support an author-defined
 824 ID. Each of the following elements have predefined IDs (shown in parentheses):
 825 </para>
 826 <informaltable>
 827 <tgroup cols="2" colsep="0" rowsep="0">
 828 <colspec colwidth="264*">
 829 <colspec colwidth="264*">
 830 <tbody>
 831 <row>
 832 <entry align="left" valign="top">&lt;PartIntro></entry>
 833 <entry align="left" valign="top">( _hometopic)</entry></row>
 834 <row>
 835 <entry align="left" valign="top">&lt;LegalNotice> in &lt;DocInfo></entry>
 836 <entry align="left" valign="top">( _copyright)</entry></row>
 837 <row>
 838 <entry align="left" valign="top">&lt;Abstract> in &lt;DocInfo></entry>
 839 <entry align="left" valign="top">( _abstract)</entry></row>
 840 <row>
 841 <entry align="left" valign="top">&lt;Glossary></entry>
 842 <entry align="left" valign="top">( _glossary)</entry></row>
 843 <row>
 844 <entry align="left" valign="top">&lt;Title> in &lt;DocInfo></entry>
 845 <entry align="left" valign="top">( _title)</entry></row></tbody></tgroup>
 846 </informaltable>
 847 </sect2>
 848 <sect2 id="HRDC.OrgH.div.45" role="Procedure">
 849 <title id="HRDC.OrgH.mkr.19">To Add an ID to a DocBook Element</title>
 850 <itemizedlist><listitem><para>You include the ID string in the opening tag
 851 of the element as follows:</para>
 852 <programlisting>&lt;Element ID="<symbol>id-string</symbol>"></programlisting>
 853 <para>Note that the value of the ID string is enclosed in quotation marks.
 854 </para>
 855 </listitem></itemizedlist>
 856 <para>All the DocBook elements with the common attributes support an author-defined
 857 ID. These are:</para>
 858 <itemizedlist><listitem><para>Abbrev</para>
 859 </listitem><listitem><para>Abstract</para>
 860 </listitem><listitem><para>Anchor</para>
 861 </listitem><listitem><para>Appendix</para>
 862 </listitem><listitem><para>Author</para>
 863 </listitem><listitem><para>BlockQuote</para>
 864 </listitem><listitem><para>BridgeHead</para>
 865 </listitem><listitem><para>Chapter</para>
 866 </listitem><listitem><para>ComputerOutput</para>
 867 </listitem><listitem><para>CorpAuthor</para>
 868 </listitem><listitem><para>DocInfo</para>
 869 </listitem><listitem><para>Entry</para>
 870 </listitem><listitem><para>EntryTbl</para>
 871 </listitem><listitem><para>Example</para>
 872 </listitem><listitem><para>Figure</para>
 873 </listitem><listitem><para>Glossary</para>
 874 </listitem><listitem><para>GlossDiv</para>
 875 </listitem><listitem><para>GlossEntry</para>
 876 </listitem><listitem><para>GlossTerm</para>
 877 </listitem><listitem><para>Graphic</para>
 878 </listitem><listitem><para>Index</para>
 879 </listitem><listitem><para>IndexDiv</para>
 880 </listitem><listitem><para>IndexEntry</para>
 881 </listitem><listitem><para>InformalTable</para>
 882 </listitem><listitem><para>ItemizedList</para>
 883 </listitem><listitem><para>KeyCap</para>
 884 </listitem><listitem><para>LiteralLayout</para>
 885 </listitem><listitem><para>OrderedList</para>
 886 </listitem><listitem><para>Part</para>
 887 </listitem><listitem><para>PrimaryIE</para>
 888 </listitem><listitem><para>ProgramListing</para>
 889 </listitem><listitem><para>Quote</para>
 890 </listitem><listitem><para>RefEntry</para>
 891 </listitem><listitem><para>Reference</para>
 892 </listitem><listitem><para>Screen</para>
 893 </listitem><listitem><para>Sect1 - Sect5</para>
 894 </listitem><listitem><para>See</para>
 895 </listitem><listitem><para>SeeAlso</para>
 896 </listitem><listitem><para>SeeIE</para>
 897 </listitem><listitem><para>Seg</para>
 898 </listitem><listitem><para>SegListItem</para>
 899 </listitem><listitem><para>SegmentedList</para>
 900 </listitem><listitem><para>SegTitle</para>
 901 </listitem><listitem><para>Sidebar</para>
 902 </listitem><listitem><para>SpanSpec</para>
 903 </listitem><listitem><para>Table</para>
 904 </listitem><listitem><para>TBody</para>
 905 </listitem><listitem><para>TFoot</para>
 906 </listitem><listitem><para>TGroup</para>
 907 </listitem><listitem><para>Term</para>
 908 </listitem><listitem><para>Title</para>
 909 </listitem><listitem><para>TitleAbbrev</para>
 910 </listitem><listitem><para>ToC</para>
 911 </listitem><listitem><para>UserInput</para>
 912 </listitem><listitem><para>VariableList</para>
 913 </listitem><listitem><para>VarListEntry</para>
 914 </listitem></itemizedlist>
 915 <para>In addition to including IDs with DocBook elements that support them,
 916 you can use the Anchor element to set an ID at an arbitrary point within a
 917 document. The Anchor can then mark a target for a Link, which will take the
 918 Anchor's ID string for the value of its Linkend attribute. Anchor is an inline
 919 element that may appear almost anywhere. Anchor is an empty element, with
 920 no content.</para>
 921 <para>Anchor can have ID, Pagenum, Remap, Role, and XRefLabel attributes,
 922 but only the ID attribute is required. At the minimum, only the Anchor start
 923 tag is present, with an ID.</para>
 924 <para>When you activate a link to a location ID, the Help Viewer displays
 925 the topic containing the ID and scrolls the window to the ID position.</para>
 926 <sect3 id="HRDC.OrgH.div.45a">
 927 <title>Syntax of the Anchor element</title>
 928 <programlisting>&lt;anchor id="<symbol>id-string</symbol>"></programlisting>
 929 </sect3>
 930 <sect3 id="HRDC.OrgH.div.45b">
 931 <title>Example of the Anchor element</title>
 932 <programlisting>There is an Anchor <symbol>&lt;anchor id=&ldquo;077-ch02-AN-7&rdquo;></symbol> in this sentence.</programlisting>
 933 </sect3>
 934 </sect2>
 935 </sect1>
 936 <sect1 id="HRDC.OrgH.div.49">
 937 <title id="HRDC.OrgH.mkr.22">Using Entities</title>
 938 <para>An <emphasis>entity</emphasis> can represent a string of characters
 939 or the contents of a file.</para>
 940 <para>An <emphasis>entity declaration</emphasis> defines the entity by associating
 941 the entity name with a specific character string or file name.</para>
 942 <para>An <emphasis>entity reference</emphasis> is replaced by the string
 943 or file contents when you process the help volume with the <command>dtdocbook</command> command.</para>
 944 <para>Entities are useful for:</para>
 945 <itemizedlist><listitem><para><emphasis>Referencing a given string of text.</emphasis> This is useful if there is some likelihood that the given string
 946 of text may subsequently need to be changed, or if you simply don't want to
 947 type it repeatedly.</para>
 948 <para>Once you have declared an entity to stand for a given string of text,
 949 each place you want the text inserted, you simply reference the entity name.
 950 </para>
 951 </listitem><listitem><para><emphasis>Referencing an external file, particularly
 952 a graphics file.</emphasis> Entities provide one way of accessing graphics
 953 files.</para>
 954 <para>The Graphic element points via its attributes to an external file containing
 955 graphical data.</para>
 956 <para>The file that contains the graphical data can be specified by using
 957 Graphic's Fileref attribute with the value of the filename, qualified by a
 958 pathname if desired.</para>
 959 <para>Alternatively, if the file that contains the graphical data has been
 960 declared an entity, it can be specified by using Graphic's Entityref with
 961 the value of the entity name.</para>
 962 </listitem></itemizedlist>
 963 <para>File entities are also useful for splitting your DocBook source into
 964 multiple files. Use entity references to include other files into your master
 965 DocBook file for processing.</para>
 966 <sect2 id="HRDC.OrgH.div.50">
 967 <title><emphasis>Rules for Entity Declarations</emphasis></title>
 968 <itemizedlist><listitem><para>Entity names may contain letters (A - Z and
 969 a - z), digits (0 - 9), the period (.), and the minus (&minus;) sign, and
 970 must begin with a letter.</para>
 971 </listitem><listitem><para>Case is <emphasis>not</emphasis> significant in
 972 entity names, but is often used to increase readability.</para>
 973 </listitem><listitem><para>Entity names cannot be longer than 128 characters.
 974 </para>
 975 </listitem><listitem><para>Each entity name must be unique within a single
 976 volume.</para>
 977 </listitem></itemizedlist>
 978 </sect2>
 979 <sect2 id="HRDC.OrgH.div.51" role="Procedure">
 980 <title id="HRDC.OrgH.mkr.23">To Create a Text Entity</title>
 981 <orderedlist><listitem><para>Declare an entity as follows:</para>
 982 <programlisting>&lt;!entity <symbol>Entityname</symbol> "<symbol>text string</symbol>"></programlisting>
 983 <para>Where <symbol>Entityname</symbol> is the name of the entity and <symbol>tex stringt</symbol> is the string that you want substituted for every reference
 984 to the entity. <emphasis>Remember, all entity declarations must be contained
 985 in the document type declaration of your help volume.</emphasis></para>
 986 </listitem><listitem><para>For each location where you want the <symbol>text
 987 string</symbol> to be inserted, enter the entity reference as follows:</para>
 988 <programlisting><symbol>&amp;Entityname;</symbol></programlisting>
 989 <para>The <literal>&amp;</literal> (ampersand) and <literal>;</literal> (semicolon)
 990 characters are required for the DocBook software to properly recognize the
 991 entity reference.</para>
 992 </listitem></orderedlist>
 993 <sect3 id="HRDC.OrgH.div.52">
 994 <title>Example</title>
 995 <para>The following line declares a text entity named Assoc that contains
 996 the string &ldquo;Society of Agricultural Engineers&rdquo;:</para>
 997 <programlisting>&lt;!entity Assoc "Society of Agricultural Engineers"></programlisting>
 998 <para>The following sentence includes a reference to the entity:</para>
 999 <programlisting>Welcome to the &amp;Assoc;.</programlisting>
1000 <para>When the help volume is processed with the DocBook software, the entity
1001 reference is replaced with the value of the entity. So, the sentence will
1002 read:</para>
1003 <para>Welcome to the Society of Agricultural Engineers.</para>
1004 </sect3>
1005 </sect2>
1006 <sect2 id="HRDC.OrgH.div.53" role="Procedure">
1007 <title id="HRDC.OrgH.mkr.24">To Create a File Entity</title>
1008 <orderedlist><listitem><para>Declare an entity as follows:</para>
1009 <programlisting>&lt;!entity <symbol role="Variable">Entityname</symbol> SYSTEM "<symbol role="Variable">filename</symbol>"></programlisting>
1010 <para>Where <symbol role="Variable">Entityname</symbol> is the name of the
1011 entity and <symbol>filename</symbol> is the name of the file. The keyword <Symbol>SYSTEM</Symbol> is required.</para>
1012 </listitem><listitem><para>Reference the entity as follows:</para>
1013 <itemizedlist><listitem><para>If the file is a text file, enter the following
1014 entity reference at each location where you want the contents of the file
1015 inserted.</para>
1016 <programlisting><symbol>&amp;Entityname;</symbol></programlisting>
1017 <para>The &amp; (ampersand) and; (semicolon) characters are required for
1018 the DocBook software to properly recognize the entity reference.</para>
1019 </listitem><listitem><para>If the file is a graphics file, include the name
1020 of the entity as the value of the Entityref attribute like this:</para>
1021 <programlisting>&lt;Graphic ID="<symbol>some-graphic-id</symbol>"Entityref=" <symbol>Entityname</symbol>">&lt;/Graphic></programlisting>
1022 </listitem></itemizedlist>
1023 </listitem></orderedlist>
1024 <sect3 id="HRDC.OrgH.div.54">
1025 <title>Example: Text File Entities</title>
1026 <para>Suppose you wrote the text for your help volume in three files named
1027 <filename>file1</filename>, <filename>file2</filename>, and <filename>file3</filename>,
1028 plus a fourth file containing your &lt;docinfo> &hellip; &lt;/docinfo> section.
1029 You could include them in your <symbol>volume</symbol><filename>.sgm</filename>
1030 file like this:</para>
1031 <programlisting>&lt;!DOCTYPE DOCBOOK [
1032 &lt;!entity DocInformation SYSTEM "docinfo">
1033 &lt;!entity MyFirstFile SYSTEM "file1">
1034 &lt;!entity MySecondFile SYSTEM "file2">
1035 &lt;!entity MyThirdFile SYSTEM "file3">
1036 .<?Pub Caret>..
1037 >]
1038
1039 &lt;Part>
1040 &amp;DocInformation;
1041 &lt;Title>My Home Title&lt;/Title>
1042
1043 &amp;MyFirstFile;
1044 &amp;MySecondFile;
1045 &amp;MyThirdFile;</programlisting>
1046 </sect3>
1047 <sect3 id="HRDC.OrgH.div.55">
1048 <title>Example: A Graphic File Entity</title>
1049 <para>Suppose a simple help volume has a Part with a Graphic in it, and graphic
1050 data for the Graphic is stored in a file named <filename>picture.tif</filename>.
1051 The following example shows how that Graphic would be included by using an
1052 entity reference.</para>
1053 <programlisting>&lt;!DOCTYPE DOCBOOK [
1054 &lt;!entity DocInformation SYSTEM &ldquo;docinfo&rdquo;>
1055 &lt;!entity MyPicture SYSTEM &ldquo;picture.tif&rdquo;>
1056 ...
1057 ]>
1058 &lt;Part>
1059 &amp;DocInformation;
1060 &lt;PartIntro>&lt;Title>A Simple Graphic&lt;/Title>
1061 &lt;Para>Welcome to my application's help volume.&lt;/Para>
1062 &lt;/Part>
1063 &lt;Figure>
1064 &lt;Title>A Picture&lt;/Title>
1065 &lt;Graphic entityref="MyPicture"> &lt;/Graphic>
1066 &lt;/Figure>
1067 &lt;/PartIntro>
1068 &lt;/Part>
1069 </programlisting>
1070 <para>The text &ldquo;A Picture&rdquo; is the figure's caption.</para>
1071 <para>The markup produces this output:</para>
1072 <graphic id="HRDC.OrgH.igrph.3" entityref="HRDC.OrgH.fig.5"></graphic>
1073 </sect3>
1074 <sect3 id="HRDC.OrgH.div.56">
1075 <title>See Also</title>
1076 <itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
1077 linkend="HRDC.WrTop.mkr.23"></para>
1078 </listitem></itemizedlist>
1079 </sect3>
1080 </sect2>
1081 </sect1>
1082 </chapter>
1083 <!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
1084 <?Pub *0000055796>