1084 lines
51 KiB
Plaintext
1084 lines
51 KiB
Plaintext
<!-- $XConsortium: ch02.sgm /main/16 1996/10/22 14:42:26 cdedoc $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<chapter id="HRDC.OrgH.div.1">
|
|
<title id="HRDC.OrgH.mkr.1">Organizing and Writing a Help Volume</title>
|
|
<para>This chapter describes the organization and components of a help source
|
|
file. It also provides a step-by-step example that shows how to process a
|
|
help source file to create an online help volume.</para>
|
|
<sect1 id="HRDC.OrgH.div.2">
|
|
<title id="HRDC.OrgH.mkr.2">Help Volume Components</title>
|
|
<para>A help volume has the following major types of components: entity declarations,
|
|
a top-level volume topic (contained in the Part element) meta information
|
|
(contained in the DocInfo element), book components (like Chapters, Sections,
|
|
Lists, and Tables), the index and the glossary.</para>
|
|
<sect2 id="HRDC.OrgH.div.3">
|
|
<title>The Top Level Element: Part</title>
|
|
<para>The <emphasis>Part</emphasis> is the top-level element in the structure
|
|
of a help volume. All other components are subelements of Part in the structural
|
|
hierarchy.</para>
|
|
<para>The structural hierarchy under Part may be several levels deep with
|
|
Chapters containing Sect1s, Sect1s containing Sect2s, Sect2s containing Sect3s,
|
|
and so on. To help prevent users from getting lost, however, you should keep
|
|
your hierarchy as shallow as possible.</para>
|
|
<para>Part may contain the following components in the following order: an
|
|
optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro,
|
|
and one or more other book components, like Chapters.</para>
|
|
<para>Part has the common attributes and a label attribute.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.4">
|
|
<title>Topics and Subtopics</title>
|
|
<para>Topics and subtopics form a hierarchy below the Part. Typically, the
|
|
first level of topics is divided into chapters, using the Chapter element.
|
|
Within a chapter, topics are organized into sections, with subtopics of a
|
|
Sect1 tagged as Sect2s, subtopics of a Sect2 tagged as Sect3s, and so on.
|
|
</para>
|
|
<para><xref role="CodeOrFigureOrTable" linkend="HRDC.OrgH.mkr.3"> shows a
|
|
simple hierarchy that includes three chapters. Each chapter contains several
|
|
first-level sections. The third chapter adds two second-level sections.</para>
|
|
<figure>
|
|
<title id="HRDC.OrgH.mkr.3">Help volume structural organization</title>
|
|
<programlisting>Part
|
|
DocInfo
|
|
Title
|
|
Chapter
|
|
Sect1
|
|
Sect1
|
|
Sect1
|
|
Chapter
|
|
Sect1
|
|
Sect2
|
|
Sect3
|
|
Sect2
|
|
Sect1
|
|
Sect1
|
|
Sect2
|
|
Sect2
|
|
Sect3</programlisting>
|
|
</figure>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.5">
|
|
<title>Entities</title>
|
|
<para>An author-defined <emphasis>entity</emphasis> can represent a string
|
|
of characters or a file name. An <emphasis>entity declaration</emphasis> defines
|
|
the entity name and the string or file it represents.</para>
|
|
<para>Entities are useful for:</para>
|
|
<itemizedlist><listitem><para><emphasis>Referencing a common string of text.</emphasis> This is useful if there is some likelihood that the text may change
|
|
or you simply don't want to type it repeatedly. Each place you want the text
|
|
inserted, you reference the entity name.</para>
|
|
</listitem><listitem><para><emphasis>Referencing an external file.</emphasis>
|
|
Entities are often used for accessing graphics files. The <Graphic> element
|
|
has an Entityref attribute, which refers to a graphic image file.</para>
|
|
</listitem></itemizedlist>
|
|
<para>All entity declarations must be entered before any other markup in your
|
|
help volume. To include an entity that you have defined, you use an <emphasis>entity reference.</emphasis></para>
|
|
<para>Entity references can be used anywhere within your help volume inside
|
|
a document type declaration. When you process your help volume with the DocBook
|
|
software, each entity reference is replaced with the text or file that the
|
|
entity represents. <xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.22">describes
|
|
how to define and use entities.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.6">
|
|
<title>Meta Information</title>
|
|
<para><emphasis>Meta information</emphasis> is <emphasis>information about
|
|
your information</emphasis>.</para>
|
|
<para>In DocBook markup, meta information about a help volume is contained
|
|
in the DocInfo element.</para>
|
|
<para>DocInfo may contain the following elements in the following order:</para>
|
|
<itemizedlist><listitem><para>Title (required)</para>
|
|
</listitem><listitem><para>TitleAbbrev (optional)</para>
|
|
</listitem><listitem><para>Subtitle (optional)</para>
|
|
</listitem><listitem><para>one or more AuthorGroups (required)</para>
|
|
</listitem><listitem><para>any number of Abstracts (optional brief descriptions
|
|
of the volume's contents)</para>
|
|
</listitem><listitem><para>a RevHistory (optional)</para>
|
|
</listitem><listitem><para>any number of LegalNotices (optional, giving information
|
|
on trademarks, copyrights, etc.)</para>
|
|
</listitem></itemizedlist>
|
|
<para>The Help System uses the meta information in DocInfo to display the
|
|
Title of a help volume and its copyright information. The Abstract description
|
|
is displayed by the desktop Help Viewer in the Front Panel. Other applications
|
|
capable of displaying help volumes could also make use of this information.
|
|
</para>
|
|
<para><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.15"> shows you
|
|
how to create a meta information section.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.7">
|
|
<title>Glossary</title>
|
|
<para>The glossary includes definitions for important terms that you've used
|
|
throughout your help volume. If a term is entered using the GlossTerm element,
|
|
then it automatically becomes a link that, when selected, displays the glossary
|
|
entry for that term.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.8">
|
|
<title id="HRDC.OrgH.mkr.4">General Markup Guidelines</title>
|
|
<para>Online help is written in ordinary text files. You use special codes,
|
|
called <emphasis>tags</emphasis>, to markup <emphasis>elements</emphasis>
|
|
within the information. The tags form a markup language called DocBook.</para>
|
|
<para>If a standard text editor is used, DocBook markup is typed. If the editor
|
|
provides a macro package, tags can be stored and inserted using command keys.
|
|
DocBook markup can also be generated using a structured editor (see <xref
|
|
role="SecTitleAndPageNum" linkend="HRDC.Intro.mkr.24">).</para>
|
|
<para>The DocBook markup language defines a hierarchy of elements that define
|
|
high-level elements, such as chapters and sections, block-oriented elements,
|
|
such as paragraphs, lists, and tables, and low level in-line elements such
|
|
as emphasized words and symbols.</para>
|
|
<sect2 id="HRDC.OrgH.div.9">
|
|
<title id="HRDC.OrgH.mkr.5">Markup in Your Source Files</title>
|
|
<para>The markup for most elements consists of a start tag and an end tag.
|
|
Start tags are entered with the element name between angle brackets (<
|
|
and >). End tags are similar, but the element name is preceded by a / (forward
|
|
slash). Case is not significant in DocBook markup tags.</para>
|
|
<programlisting><Element attribute name="attribute value"> ... text ... </Element>
|
|
</programlisting>
|
|
<para>For example, to mark the start and end of a book title you use markup
|
|
like this:</para>
|
|
<programlisting><Title id="GSNW">Geographical Survey of Northern Wisconsin</Title>
|
|
</programlisting>
|
|
<para>Where <Title> is the start tag, and </Title> is the end tag, and
|
|
GSNW is the value of the ID attribute of the Title element. If the element
|
|
has more than one attribute with a specified value, the <symbol>attribute
|
|
name</symbol>="<symbol>attribute value</symbol>" expressions are separated
|
|
by spaces.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.13">
|
|
<title id="HRDC.OrgH.mkr.7">A Help Volume at a Glance</title>
|
|
<para>The following schematic markup illustrates important elements of a help
|
|
volume and the tags used to enter them. Indentation is used here simply to
|
|
highlight the hierarchical relationship of the elements; you don't need to
|
|
indent the help files that you write.</para>
|
|
<programlisting>DocType
|
|
Part
|
|
DocInfo
|
|
Title
|
|
AuthorGroup
|
|
Abstract
|
|
LegalNotice
|
|
Title
|
|
PartIntro
|
|
Chapter
|
|
Title
|
|
Sect1
|
|
Title
|
|
Para
|
|
Para
|
|
Sect2
|
|
Title
|
|
Para
|
|
Sect3
|
|
Title
|
|
Para
|
|
Para
|
|
Sect2
|
|
Title
|
|
Para
|
|
Chapter
|
|
Title
|
|
Sect1
|
|
Title
|
|
Para
|
|
Para
|
|
Sect2
|
|
Title
|
|
Para
|
|
Sect2
|
|
Title
|
|
Para
|
|
Glossary
|
|
</programlisting>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.14">
|
|
<title id="HRDC.OrgH.mkr.8">Help Source Files</title>
|
|
<para>Online help is written in ordinary text files. You process, or compile,
|
|
these files with the DocBook software to create run-time help files that can
|
|
be read by the Help System.</para>
|
|
<sect2 id="HRDC.OrgH.div.15">
|
|
<title>Creating Your volume.sgm File</title>
|
|
<para>DocBook expects a primary control file named <symbol>volume</symbol><filename>.sgm</filename>, where <symbol role="Variable">volume</symbol> is a name you
|
|
choose.</para>
|
|
<para>Be sure your <symbol role="Variable">volume</symbol> name is unique
|
|
and meaningful. If your <symbol role="Variable">volume</symbol> name is too
|
|
general, it may conflict with another volume that someone else has created.
|
|
If you are writing application help, one recommended practice is to use the
|
|
application's class name.</para>
|
|
<sect3 id="HRDC.OrgH.div.16">
|
|
<title>Multiple Source Files</title>
|
|
<para>The named <symbol>volume</symbol><filename>.sgm</filename> file contains
|
|
entity declarations and entity references to files that make up the help volume.
|
|
Although DocBook expects a single <symbol role="Variable">volume</symbol><filename>.sgm</filename> file as input, you can separate your work into multiple source
|
|
files. Additional files are sourced into the <symbol role="Variable">volume</symbol><filename>.sgm</filename> file using <emphasis>file entities</emphasis>.
|
|
A file entity is like a pointer to another file. That file, in effect, is
|
|
inserted wherever the entity's name appears in the <symbol>volume</symbol><filename>.sgm</filename> file. The referenced files can also contain entity references
|
|
to yet other files.</para>
|
|
</sect3>
|
|
<sect3 id="HRDC.OrgH.div.17">
|
|
<title>Example</title>
|
|
<para>Suppose a help volume has six chapters and each chapter is a separate
|
|
file. The files are: HomeTopic, Metainfo, TOC, Tasks, Reference, and Glossary.
|
|
The <symbol>volume</symbol><filename>.sgm</filename> file for the help volume
|
|
includes file entities for each of the six files and a list of entity references
|
|
that instruct the DocBook software to process the files.</para>
|
|
<programlisting>...
|
|
<!entity HomeTopic FILE “HomeTopic”>
|
|
<!entity MetaInformation FILE “Metainfo”>
|
|
<!entity TableOfContents FILE “TOC”>
|
|
<!entity Tasks FILE “Tasks”>
|
|
<!entity Reference FILE “Reference”>
|
|
<!entity Glossary FILE “Glossary”>
|
|
...
|
|
&HomeTopic;
|
|
&MetaInformation;
|
|
&TableOfContents;
|
|
&Tasks;
|
|
&Reference;
|
|
&Glossary;
|
|
</programlisting>
|
|
<para>The details of running DocBook are covered in <xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.CrHV.mkr.3">.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.18">
|
|
<title id="HRDC.OrgH.mkr.9">Help Files in File Manager</title>
|
|
<para>File Manager represents help files as file icons with a question mark.
|
|
In <xref role="CodeOrFigureOrTable" linkend="HRDC.OrgH.mkr.10"> on <xref role="PageNum"
|
|
linkend="HRDC.OrgH.mkr.10">, there is one source file (the one with the
|
|
<filename>.sgm</filename>) and one run-time file (<filename>.sdl</filename> extension).
|
|
If you double-click a markup file, your standard editor opens the file for
|
|
editing. Double-clicking a (<filename>.sdl</filename> extension) file displays
|
|
the run-time file using the Help Viewer.</para>
|
|
<figure>
|
|
<title id="HRDC.OrgH.mkr.10">File Manager view of help files</title>
|
|
<graphic id="HRDC.OrgH.grph.2" entityref="HRDC.OrgH.fig.2"></graphic>
|
|
</figure>
|
|
<para>To create a run-time help volume, first select the <filename>.sgm</filename>
|
|
file icon in File Manager. Then, choose Compile from the File Manager Selected
|
|
menu.</para>
|
|
<sect2 id="HRDC.OrgH.div.19">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><filename moreinfo="RefEntry">dthelpaction(4)</filename> man page</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.20">
|
|
<title id="HRDC.OrgH.mkr.11">Writing Your First Help Volume: A Step-by-Step Example</title>
|
|
<para>Typically you organize your help files in a <filename>help</filename>
|
|
directory. This step-by-step example demonstrates how to create and view a
|
|
standalone help volume. (As a standalone volume, it does not involve interaction
|
|
with an application.)</para>
|
|
<para>To create and process a help volume, you follow these steps:</para>
|
|
<orderedlist><listitem><para>Create the source directory for help files.</para>
|
|
</listitem><listitem><para>Create the master DocBook file.</para>
|
|
</listitem><listitem><para>Create the run-time help files.</para>
|
|
</listitem><listitem><para>Display the help volume.</para>
|
|
</listitem></orderedlist>
|
|
<para>Each task is described in the section that follows. The markup language
|
|
used in the text files is introduced later in this chapter. DocBook markup
|
|
is described more fully in <xref role="ChapNumAndTitle" linkend="HRDC.WrTop.mkr.1">
|
|
and in the <citetitle>Guide to the DocBook DTD</citetitle>.</para>
|
|
<sect2 id="HRDC.OrgH.div.21">
|
|
<title>Create the Source Directory</title>
|
|
<orderedlist><listitem><para>Create a directory named <filename>helpfiles</filename> where you will create and process your help files.</para>
|
|
</listitem><listitem><para>Create a text file named <filename>Commands.sgm</filename> in the directory just created.</para>
|
|
<para>For this example, all the information is put into a single file. Typically,
|
|
you will use multiple files to fully explain the system or application you
|
|
are writing help for.</para>
|
|
<para>The <filename>Commands.sgm</filename> file contains text and element
|
|
tags. The element tags within the < and > (angle brackets) indicate the
|
|
structure of the information.</para>
|
|
</listitem><listitem><para>Type the following markup text in the
|
|
<filename>Commands.sgm</filename> file.</para>
|
|
<programlisting>
|
|
<Chapter>
|
|
<Title id="CommandSummary-id>Command Summary</Title>
|
|
<Indexterm><Primary>commands<Primary></Indexterm>
|
|
<Para>Your&product; is capable of the following operations:</Para>
|
|
<ItemizedList>
|
|
<ListItem><Para><Link Linkend="ChannelChange-id">ChannelChange</Link></Para></ListItem>
|
|
<ListItem><Para><Link Linkend="VolumeUp-id"> VolumeUp </Link> </Para></ListItem>
|
|
<ListItem><Para><Link Linkend="VolumeDown-id"> VolumeDown </Link></Para></ListItem>
|
|
<ListItem><Para><Link Linkend="VolumeMute-id"> VolumeMute </Link></Para></ListItem>
|
|
</ItemizedList>
|
|
<Para>Choose one of the hyperlinks (underlined phrases)
|
|
to find out how to perform that operation.</Para>
|
|
<Sect1 id="ChannelChange-s">
|
|
<Title id="ChannelChange-t">Changing the Channel</Title>
|
|
<Indexterm><Primary>channel<Secondary>changing</Secondary><Primary></Indexterm>
|
|
<Para>Speak the command:
|
|
<Programlisting> channel</Programlisting>
|
|
followed by a number from <Command>one</Command>to <Command>ninety-nine</Command>.</Para>
|
|
</Sect1>
|
|
<Sect1 id="VolumeUp-s">
|
|
<Title id="VolumeUp-t">Turning Up the Volume</Title>
|
|
<Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
|
|
<Para>Speak the command:
|
|
<Programlisting>volume up</Programlisting></Para>
|
|
<Para>For additional volume, speak the command:
|
|
<Programlisting>more</Programlisting></para>
|
|
<Para>(See also <Link Linkend="VolumeDown-id">VolumeDown</Link>)</Para>
|
|
</Sect1>
|
|
<Sect1 id="VolumeDown-s">
|
|
<Title id="VolumeDown-t">Turning Down the Volume</Title>
|
|
<Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
|
|
<Para>Speak the command:
|
|
<Programlisting>volume down</Programlisting></Para>
|
|
<Para>To reduce the volume further, speak the command:
|
|
<Programlisting>more</Programlisting></Para>
|
|
<Para>(See also <Link Linkend="VolumeUp-id"> VolumeUp </Link> and <Link Linkend="VolumeMute-id">VolumeMute</Link>)</Para>
|
|
</Sect1>
|
|
<Sect1 id="VolumeMute-s">
|
|
<Title id="VolumeMute-t">Turning Off the Sound</Title>
|
|
<Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
|
|
<Indexterm><Primary>sound<Secondary>on/off</Secondary></Primary></Indexterm>
|
|
<Para>Speak the command:
|
|
<Programlisting>sound off</Programlisting></Para>
|
|
<Para>To restore the sound, speak the command:
|
|
<Programlisting>sound on</Programlisting></Para>
|
|
<Para>(See also <Link Linkend="VolumeDown-id">VolumeDown</Link> and <Link Linkend="VolumeUp-id">VolumeUp</Link></Para>
|
|
</Sect1>
|
|
</Chapter>
|
|
</programlisting>
|
|
</listitem><listitem><para>Create a text file that gives the information a
|
|
title, provides copyright information, and provides other information about
|
|
the online help.</para>
|
|
<para>In this example, the following text is put into a file called
|
|
<filename>Metainfo.sgm</filename> in the same directory as the <filename>Commands.sgm</filename>file.</para>
|
|
<programlisting><DocInfo>
|
|
<Title> Using the &product;</Title>
|
|
<AuthorGroup><Author>Jim Jonas</Author>
|
|
</AuthorGroup>
|
|
<Abstract> Help for Using the &product;.
|
|
</Abstract>
|
|
<LegalNotice>
|
|
<BlockQuote>
|
|
<para>&copy; 1995 Voice Activation Company.
|
|
All rights reserved.</para>
|
|
</BlockQuote>
|
|
</LegalNotice>
|
|
</DocInfo>
|
|
</programlisting>
|
|
</listitem></orderedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.23">
|
|
<title>Create the Master DocBook File</title>
|
|
<orderedlist><listitem><para>Create a text file whose name is of the form <symbol role="Variable">volume</symbol><filename>.sgm</filename>. In this example,
|
|
the file is named <filename>voiceact.sgm</filename>.</para>
|
|
</listitem><listitem><para>In the <filename>voiceact.sgm</filename> file,
|
|
define <emphasis>entities</emphasis> that associate the names of the
|
|
<filename>Commands.sgm</filename> and <filename>Metainfo.sgm</filename> files with entity
|
|
names. Also, define any entities that are used (either directly or indirectly)
|
|
in the <filename>Commands.sgm</filename> and <filename>Metainfo.sgm</filename>
|
|
files. Finally, refer to the <filename>Commands.sgm</filename> and
|
|
<filename>Metainfo.sgm</filename> files by their entity names.</para>
|
|
</listitem></orderedlist>
|
|
<para>In this example, the contents of the <filename>voiceact.sgm</filename>
|
|
file look like this. The text within the <literal><!--…--></literal>
|
|
elements are comments, which are ignored.</para>
|
|
<programlisting><!-- Declare an entity for each of the source text files. -->
|
|
<!entity MetaInformation FILE “Metainfo”>
|
|
<!entity Commands FILE “Commands”>
|
|
|
|
<!-- Define an entity that names the product and includes
|
|
the trademark symbol (&tm;). -->
|
|
|
|
<!entity product “VoAc&tm; Voice-Activated Remote Control”>
|
|
|
|
<!-- Include the text files. -->
|
|
<Part>
|
|
&MetaInformation;
|
|
&Commands;
|
|
</Part></programlisting>
|
|
</sect2>
|
|
<sect2 id="hrdc.orgh.div.25">
|
|
<title>Create the Run-Time Help Files</title>
|
|
<orderedlist><listitem><para>Verify that the <filename>/usr/dt/bin</filename>
|
|
directory is in your search path by typing this command in a terminal window:
|
|
</para>
|
|
<para><command>echo $PATH</command></para>
|
|
<para>If the directory is not in your path, add it to your PATH environment
|
|
variable. If you're not sure how to do this, refer to your system documentation
|
|
or ask your system administrator.</para>
|
|
</listitem><listitem><para>Open File Manager and change to the
|
|
<filename>helpfiles</filename> directory. Select the <filename>voiceact.sgm</filename>
|
|
file icon and choose Compile from the Selected menu in File Manager.</para>
|
|
<para>This executes the DocBook software which creates a run-time version
|
|
of your online help volume (<filename>voiceact.sdl</filename>). Status and
|
|
error messages are placed in a new file, whose name is of the form <symbol>volume</symbol><filename>.log</filename>.</para>
|
|
</listitem><listitem><para>Open the <filename>voiceact.log</filename> file
|
|
to check that your file processed without errors. If errors occurred, fix
|
|
them by editing or renaming the text files as needed.</para>
|
|
</listitem></orderedlist>
|
|
<note>
|
|
<para>You can run DocBook manually in a terminal window.</para>
|
|
<para>To do so, execute the following command:</para>
|
|
<para><command>dtdocbook voiceact.sgm</command></para>
|
|
</note>
|
|
</sect2>
|
|
<sect2 id="hrdc.orgh.div.26">
|
|
<title>Display the Help Volume</title>
|
|
<para>From the <filename>helpfiles</filename> directory, double-click the
|
|
<filename>voiceact.sdl</filename> file icon.</para>
|
|
<para>This displays the help volume using the desktop Help Viewer. You can
|
|
now scroll through the information and jump to related information by choosing
|
|
hyperlinks.</para>
|
|
<note>
|
|
<para>You can run the Help Viewer manually in a terminal window.</para>
|
|
<para>To do so, execute the following command, which displays the new help
|
|
volume:</para>
|
|
<para><command>dthelpview -h voiceact.sdl</command></para>
|
|
</note>
|
|
<sect3 id="hrdc.orgh.div.27">
|
|
<title>See Also</title>
|
|
<itemizedlist><listitem><para><xref role="ChapNumAndTitle" linkend="hrdc.crhv.mkr.1">,
|
|
on <xref role="PageNum" linkend="hrdc.crhv.mkr.1"></para>
|
|
</listitem><listitem><para><xref role="ChapNumAndTitle" linkend="hrdc.cmds.mkr.1">,
|
|
on <xref role="PageNum" linkend="hrdc.cmds.mkr.1"></para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.28">
|
|
<title id="HRDC.OrgH.mkr.12">Creating a Topic Hierarchy</title>
|
|
<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
|
|
below Part must be entered with <Chapter> tags.</para>
|
|
<para>Additional levels of subtopics are entered with <Sect1>, <Sect2>,
|
|
<Sect3>, <Sect4>, and <Sect5>. The DocBook markup language supports
|
|
five topic levels, but bear in mind that information more than three or four
|
|
levels deep often leads many readers to feel lost.</para>
|
|
<para>When a help volume is displayed, the help window displays a list of
|
|
topics in its topic tree. Any topic entered with a <Chapter>, <Sect1>,
|
|
<Sect2>, <Sect3>, <Sect4>, or <Sect5> tag automatically appears
|
|
in the topic tree. This provides an easy way to browse and view topics.</para>
|
|
<para>To enable users to display other related information from within a topic,
|
|
you create hyperlinks. To do so, you assign a unique ID to each destination
|
|
topic. Hyperlinks make it possible to reference a specific ID anywhere in
|
|
your help information.</para>
|
|
<sect2 id="HRDC.OrgH.div.29">
|
|
<title>Example</title>
|
|
<para>Suppose you want to create a hierarchy to match this simple outline:
|
|
</para>
|
|
<programlisting>Tutorial for New Users
|
|
Module 1: Getting Started
|
|
Module 2: Creating Your First Report
|
|
Module 3: Printing the Report
|
|
Module 4: Saving Your Work and Quitting
|
|
Task Reference
|
|
Starting and Stopping
|
|
To Start the Program
|
|
To Quit the Program
|
|
Creating Reports
|
|
To Create a Detailed Report
|
|
To Create a Summary Report
|
|
Concepts for Advanced Users
|
|
Using Report Hot Links
|
|
Sharing Reports within a Workgroup
|
|
Reference
|
|
Command Summary
|
|
Report Attributes Summary</programlisting>
|
|
<para>Then the general outline of your help volume would look like this.</para>
|
|
<programlisting><Part>
|
|
<title>Welcome to ReportMaster</title>
|
|
|
|
<chapter>
|
|
<title>Tutorial for New Users</title>
|
|
overview of chapter topic
|
|
<sect1>
|
|
<title>Module 1: Getting Started</title>
|
|
body of topic
|
|
</sect1>
|
|
<sect1>
|
|
<title>Module 2: Creating Your First Report</title>
|
|
body of topic
|
|
</sect1>
|
|
<sect1>
|
|
<title>Module 3: Printing the Report</title>
|
|
body of topic
|
|
</sect1>
|
|
<sect1>
|
|
<title>Module 4: Saving Your Work and Quitting</title>
|
|
body of topic
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Task Reference</title>
|
|
overview of chapter topic
|
|
<sect1>
|
|
<title>Starting and Stopping</title>
|
|
body of topic
|
|
<sect2>
|
|
<title>To Start the Program</title>
|
|
body of topic
|
|
</sect2>
|
|
<sect2>
|
|
<title>To Quit the Program</title>
|
|
body of topic
|
|
</sect2>
|
|
<sect1>
|
|
<title>Creating Reports</title>
|
|
body of topic
|
|
<sect2>
|
|
<title>To Create a Detailed Report</title>
|
|
body of topic
|
|
</sect2>
|
|
<sect2>
|
|
<title>To Create a Summary Report</title>
|
|
body of topic
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Concepts for Advanced Users</title>
|
|
overview of chapter topic
|
|
<sect1>
|
|
<title>Using Report Hot Links</title>
|
|
body of topic
|
|
</sect1>
|
|
<sect1>
|
|
<title>Sharing Reports within a Workgroup</title>
|
|
body of topic
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Reference</title>
|
|
overview of chapter topic
|
|
<sect1>
|
|
<title>Command Summary</title>
|
|
body of topic
|
|
</sect1>
|
|
<sect1>
|
|
<title>Report Attributes Summary</title>
|
|
body of topic
|
|
</sect1>
|
|
</chapter>
|
|
</part></programlisting>
|
|
<para>(The body of each topic and IDs for the topics are not shown. Spacing
|
|
and indentations are only for ease of reading, and are not significant.)</para>
|
|
<sect3 id="HRDC.OrgH.div.30">
|
|
<title>See Also</title>
|
|
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.18">describes
|
|
assigning IDs to topics</para>
|
|
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.WrTop.mkr.14">describes
|
|
how to create hyperlinks</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="hrdc.orgh.div.31" role="Procedure">
|
|
<title id="hrdc.orgh.mkr.13">To Create a Part</title>
|
|
<itemizedlist><listitem><para>Use the Part element as follows:</para>
|
|
</listitem></itemizedlist>
|
|
<programlisting><Part>
|
|
<DocInfo>
|
|
<Title>Volume Title</Title>
|
|
<AuthorGroup>
|
|
<Author>author's name here</Author>
|
|
</AuthorGroup>
|
|
<Abstract>
|
|
<Para>abstract here</Para>
|
|
</Abstract>
|
|
<LegalNotice>
|
|
<BlockQuote>
|
|
<Para>copyrights etc. </Para>
|
|
</BlockQuote>
|
|
</LegalNotice>
|
|
</DocInfo>
|
|
<Title>Volume Title</Title>
|
|
</PartIntro><Para>This is the home topic.</Para></PartIntro>
|
|
<Chapter Id="chapid">
|
|
<Title>This Chapter</Title>
|
|
<Sect1 Id="sect1id">
|
|
<Title>Sect1 Heading</Title>
|
|
<Sect2 Id="sect2id">
|
|
<Title>Sect2 Heading</Title>
|
|
...
|
|
...
|
|
...
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
</Part>
|
|
</programlisting>
|
|
<para>Part may contain the following components in the following order: an
|
|
optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro,
|
|
and one or more other book components, like Chapters and Sections.</para>
|
|
<para>Note that the Title of the help volume appears twice, if a DocInfo is
|
|
present: once within DocInfo, and again as the first element following DocInfo.
|
|
</para>
|
|
<sect3 id="hrdc.orgh.div.32">
|
|
<title>Example</title>
|
|
<para>Here's a sample Part with a PartIntro that includes hyperlinks to the
|
|
Part's four subtopics:</para>
|
|
<programlisting>
|
|
</Part>
|
|
<title>Report Master</title>
|
|
<PartIntro>
|
|
<Para>Welcome to the online help for Report Master. Please choose one of the following hyperlinks:</Para>
|
|
<itemizedlist>
|
|
<listitem><para><Link Linkend="Tutorial-id">Tutorial</Link> </para></listitem>
|
|
<listitem><para><Link Linkend="Tasks-id">Tasks</Link></para></listitem>
|
|
<listitem><para><Link Linkend="Concepts-id">VolumeDown</Link></para></listitem>
|
|
<listitem><para><Link Linkend="Reference-id">VolumeMute</Link></para></listitem>
|
|
</itemizedlist>.
|
|
<Para>If you need help, press F1.</Para>
|
|
</PartIntro>
|
|
...
|
|
</Part></programlisting>
|
|
<para>The preceding markup produces this output:</para>
|
|
<graphic id="hrdc.orgh.igrph.2" entityref="HRDC.OrgH.fig.4"></graphic>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="hrdc.orgh.div.33" role="Procedure">
|
|
<title id="hrdc.orgh.mkr.14">To Add a Topic to the Hierarchy</title>
|
|
<itemizedlist><listitem><para>To add another topic at the same level, close
|
|
the element using its end tag, then repeat the same element by opening it
|
|
with its start tag.</para>
|
|
<para>To add a subtopic (a topic one level deeper in the hierarchy), use the
|
|
element that is one level deeper than the preceding topic.</para>
|
|
</listitem></itemizedlist>
|
|
<sect3 id="hrdc.orgh.div.34">
|
|
<title>Example</title>
|
|
<para>If the current topic is a <Sect1>, enter a subtopic using <Sect2>.
|
|
</para>
|
|
<programlisting><sect1>
|
|
<title>Creating Reports</title>
|
|
body of the topic
|
|
<sect2>
|
|
<title>To Create a Detailed Report</title>
|
|
body of the first subtopic
|
|
</sect2>
|
|
<sect2>
|
|
<title>To Create a Summary Report</title>
|
|
body of the second subtopic
|
|
</sect2>
|
|
</sect1></programlisting>
|
|
<para>The second Sect2 is also a subtopic of the Sect1.</para>
|
|
<note>
|
|
<para>Sometimes parent-child-sibling metaphors are used to describe the relationships
|
|
topics in a hierarchy. In the preceding example, the Sect1 topic is the “parent”
|
|
of both Sect2s (the “children” topics). The two Sect2s are “siblings”
|
|
of one another. All three topics are “descendents” of the Chapter's
|
|
topic.</para>
|
|
</note>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.35">
|
|
<title id="HRDC.OrgH.mkr.15">Creating Meta Information Topics</title>
|
|
<para>The DocInfo meta information section is primarily intended for <emphasis>information about information</emphasis>. In the DocBook markup language,
|
|
Meta information for a help volume is contained in the DocInfo element that
|
|
may occur as the first component of a Part. DocInfo contains information about
|
|
the help volume's title and authors, may contain legal notices about copyrights
|
|
and trademarks, and abstracts of the volume's contents.</para>
|
|
<para>DocInfo may contain the following elements in the following order:</para>
|
|
<itemizedlist><listitem><para>Title (required)</para>
|
|
</listitem><listitem><para>TitleAbbrev (optional)</para>
|
|
</listitem><listitem><para>Subtitle (optional)</para>
|
|
</listitem><listitem><para>one or more AuthorGroups (required)</para>
|
|
</listitem><listitem><para>any number of Abstracts (optional)</para>
|
|
</listitem><listitem><para>a RevHistory (optional)</para>
|
|
</listitem><listitem><para>any number of LegalNotices (optional)</para>
|
|
</listitem></itemizedlist>
|
|
<sect2 id="HRDC.OrgH.div.36" role="Procedure">
|
|
<title id="HRDC.OrgH.mkr.16">To Create a Meta Information Section</title>
|
|
<orderedlist><listitem><para>Enter the <DocInfo> tag to start the section,
|
|
and follow immediately with the required Title element, as shown:</para>
|
|
<programlisting><DocInfo>
|
|
<title><symbol>Volume Title Here</symbol></title>
|
|
</programlisting>
|
|
</listitem><listitem><para>Enter the optional TitleAbbrev and Subtitle elements
|
|
if needed.</para>
|
|
</listitem><listitem><para>Enter the required AuthorGroup element, which contains
|
|
one or more Authors, Collabs, or CorpAuthors, in any order.</para>
|
|
</listitem><listitem><para>Enter the optional Abstract and LegalNotice elements
|
|
if needed, following these syntax models:</para>
|
|
<programlisting><Abstract Id="SDL-RESERVED-abstract">
|
|
<Para>abstract here</Para>
|
|
</Abstract>
|
|
|
|
<LegalNotice Id="SDL-RESERVED-copyright">
|
|
<BlockQuote>
|
|
<Para>© year & copyright holder's name</Para>
|
|
</BlockQuote>
|
|
</LegalNotice>
|
|
</programlisting>
|
|
</listitem><listitem><para>Enter the DocInfo end tag to end the section.</para>
|
|
</listitem></orderedlist>
|
|
<para>The Abstract section is recommended. Applications that access help volumes
|
|
can use this information to present a brief description of the volume. Because
|
|
the abstract might be displayed in plain text windows avoid including any
|
|
DocBook markup in the abstract.</para>
|
|
<sect3 id="HRDC.OrgH.div.37">
|
|
<title>Example</title>
|
|
<para>Here's a markup for typical meta information section contained in the
|
|
DocInfo element:</para>
|
|
<programlisting>
|
|
<DocInfo>
|
|
<title>Report Master, Version 1.0</title>
|
|
|
|
<AuthorGroup>
|
|
<Author>Jim Jonas</Author>
|
|
</AuthorGroup>
|
|
|
|
<Abstract>
|
|
<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.</Para>
|
|
</Abstract>
|
|
|
|
<LegalNotice>
|
|
<BlockQuote>
|
|
<Para>
|
|
Version 1.0
|
|
&copy; Copyright Reports Incorporated 1995
|
|
All rights reserved.
|
|
</Para>
|
|
</BlockQuote>
|
|
</LegalNotice>
|
|
</DocInfo></programlisting>
|
|
<para>The BlockQuote element is used to preserve the line breaks in the copyright
|
|
notice. The <literal>&copy;</literal> entity inserts the copyright symbol.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.39">
|
|
<title>Adding a Nonhierarchical Topic</title>
|
|
<para>Topics entered with the Chapter, Sect1, Sect2, Sect3, Sect4, Sect5 element
|
|
tags automatically appear in the topic tree. When a title is selected in the
|
|
topic tree, the corresponding help topic is displayed in a general help dialog
|
|
box.</para>
|
|
<para>Sometimes you may want to create and display a topic independent of
|
|
the structural hierarchy you have created. These nonhierarchical topics are
|
|
useful for creating custom definition links that pop-up a topic in a quick
|
|
help dialog box.</para>
|
|
<para>Appendix is the tag for a free-floating heading not tied to the Sect
|
|
hierarchy. It may contain inline elements.</para>
|
|
<para>Appendix has the common attributes, including the ID attribute and the
|
|
XRefLabel atttribute, and also the Label attribute. When using the Appendix
|
|
element for nonhierarchical topics, the value of the Role attribute should
|
|
be “notoc”.</para>
|
|
<sect2 id="hrdc.orgh.div.40" role="Procedure">
|
|
<title id="hrdc.orgh.mkr.17">To Add a Nonhierarchical Topic</title>
|
|
<itemizedlist><listitem><para>Add the nonhierarchical topic using the BridgeHead
|
|
element as follows:</para>
|
|
<programlisting><Appendix id="bh-some-id" role="notoc">
|
|
<symbol>text of the topic</symbol>
|
|
</Appendix></programlisting>
|
|
</listitem></itemizedlist>
|
|
<para>Presumably, a definition link to display this topic will exist within
|
|
some other topic in the help volume.</para>
|
|
<para>The link might look like this:</para>
|
|
<programlisting>Here's a sample of a pop-up <link linkend="bh-some-id">
|
|
definition link.</link></programlisting>
|
|
<para>The words “definition link” become the active hyperlink
|
|
and will be displayed with a dashed underline. Selecting the link displays
|
|
the text of the topic in a quick help dialog box.</para>
|
|
<sect3 id="hrdc.orgh.div.42">
|
|
<title>See Also</title>
|
|
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="hrdc.wrtop.mkr.14"></para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.43">
|
|
<title id="HRDC.OrgH.mkr.18">Accessing Topics</title>
|
|
<para>Many elements in the DocBook language support an ID attribute. An ID
|
|
is a unique name used internally to identify topics and elements within topics.
|
|
Since ID is one of DocBook's common attributes, any element with the common
|
|
attributes can support an ID attribute.</para>
|
|
<para>An ID is defined only once, but multiple hyperlinks and cross-references
|
|
can refer to the same ID. IDs are not seen by the user.</para>
|
|
<para>If you are writing help for an application, IDs are also used by the
|
|
application to identify particular topics to display when the user requests
|
|
help.</para>
|
|
<para>For example, you might write several topics that describe an application's
|
|
menus. The IDs that you assign to the topics are used by the application developer.
|
|
By defining identical IDs within the application code, the developer can integrate
|
|
specific topics. This allows the application to access and display the correct
|
|
topic when help is requested for a particular menu.</para>
|
|
<sect2 id="HRDC.OrgH.div.44">
|
|
<title>Rules for ID Names</title>
|
|
<itemizedlist><listitem><para>ID strings may contain letters (A - Z and a
|
|
- z), digits (0 - 9), the period (.), and the minus (−) sign. ID strings
|
|
must begin with a letter, and be unique at least within the document in which
|
|
they occur.</para>
|
|
</listitem><listitem><para>Case in ID strings is <emphasis>not</emphasis>
|
|
significant, but is often used to increase readability.</para>
|
|
</listitem><listitem><para>ID strings cannot be longer than 128 characters.
|
|
</para>
|
|
</listitem><listitem><para>Each ID within a single help volume must be unique.
|
|
</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.44a">
|
|
<title>Built-in IDs</title>
|
|
<para>A few elements have built-in IDs, and so do not support an author-defined
|
|
ID. Each of the following elements have predefined IDs (shown in parentheses):
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec colwidth="264*">
|
|
<colspec colwidth="264*">
|
|
<tbody>
|
|
<row>
|
|
<entry align="left" valign="top"><PartIntro></entry>
|
|
<entry align="left" valign="top">( _hometopic)</entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><LegalNotice> in <DocInfo></entry>
|
|
<entry align="left" valign="top">( _copyright)</entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><Abstract> in <DocInfo></entry>
|
|
<entry align="left" valign="top">( _abstract)</entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><Glossary></entry>
|
|
<entry align="left" valign="top">( _glossary)</entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><Title> in <DocInfo></entry>
|
|
<entry align="left" valign="top">( _title)</entry></row></tbody></tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.45" role="Procedure">
|
|
<title id="HRDC.OrgH.mkr.19">To Add an ID to a DocBook Element</title>
|
|
<itemizedlist><listitem><para>You include the ID string in the opening tag
|
|
of the element as follows:</para>
|
|
<programlisting><Element ID="<symbol>id-string</symbol>"></programlisting>
|
|
<para>Note that the value of the ID string is enclosed in quotation marks.
|
|
</para>
|
|
</listitem></itemizedlist>
|
|
<para>All the DocBook elements with the common attributes support an author-defined
|
|
ID. These are:</para>
|
|
<itemizedlist><listitem><para>Abbrev</para>
|
|
</listitem><listitem><para>Abstract</para>
|
|
</listitem><listitem><para>Anchor</para>
|
|
</listitem><listitem><para>Appendix</para>
|
|
</listitem><listitem><para>Author</para>
|
|
</listitem><listitem><para>BlockQuote</para>
|
|
</listitem><listitem><para>BridgeHead</para>
|
|
</listitem><listitem><para>Chapter</para>
|
|
</listitem><listitem><para>ComputerOutput</para>
|
|
</listitem><listitem><para>CorpAuthor</para>
|
|
</listitem><listitem><para>DocInfo</para>
|
|
</listitem><listitem><para>Entry</para>
|
|
</listitem><listitem><para>EntryTbl</para>
|
|
</listitem><listitem><para>Example</para>
|
|
</listitem><listitem><para>Figure</para>
|
|
</listitem><listitem><para>Glossary</para>
|
|
</listitem><listitem><para>GlossDiv</para>
|
|
</listitem><listitem><para>GlossEntry</para>
|
|
</listitem><listitem><para>GlossTerm</para>
|
|
</listitem><listitem><para>Graphic</para>
|
|
</listitem><listitem><para>Index</para>
|
|
</listitem><listitem><para>IndexDiv</para>
|
|
</listitem><listitem><para>IndexEntry</para>
|
|
</listitem><listitem><para>InformalTable</para>
|
|
</listitem><listitem><para>ItemizedList</para>
|
|
</listitem><listitem><para>KeyCap</para>
|
|
</listitem><listitem><para>LiteralLayout</para>
|
|
</listitem><listitem><para>OrderedList</para>
|
|
</listitem><listitem><para>Part</para>
|
|
</listitem><listitem><para>PrimaryIE</para>
|
|
</listitem><listitem><para>ProgramListing</para>
|
|
</listitem><listitem><para>Quote</para>
|
|
</listitem><listitem><para>RefEntry</para>
|
|
</listitem><listitem><para>Reference</para>
|
|
</listitem><listitem><para>Screen</para>
|
|
</listitem><listitem><para>Sect1 - Sect5</para>
|
|
</listitem><listitem><para>See</para>
|
|
</listitem><listitem><para>SeeAlso</para>
|
|
</listitem><listitem><para>SeeIE</para>
|
|
</listitem><listitem><para>Seg</para>
|
|
</listitem><listitem><para>SegListItem</para>
|
|
</listitem><listitem><para>SegmentedList</para>
|
|
</listitem><listitem><para>SegTitle</para>
|
|
</listitem><listitem><para>Sidebar</para>
|
|
</listitem><listitem><para>SpanSpec</para>
|
|
</listitem><listitem><para>Table</para>
|
|
</listitem><listitem><para>TBody</para>
|
|
</listitem><listitem><para>TFoot</para>
|
|
</listitem><listitem><para>TGroup</para>
|
|
</listitem><listitem><para>Term</para>
|
|
</listitem><listitem><para>Title</para>
|
|
</listitem><listitem><para>TitleAbbrev</para>
|
|
</listitem><listitem><para>ToC</para>
|
|
</listitem><listitem><para>UserInput</para>
|
|
</listitem><listitem><para>VariableList</para>
|
|
</listitem><listitem><para>VarListEntry</para>
|
|
</listitem></itemizedlist>
|
|
<para>In addition to including IDs with DocBook elements that support them,
|
|
you can use the Anchor element to set an ID at an arbitrary point within a
|
|
document. The Anchor can then mark a target for a Link, which will take the
|
|
Anchor's ID string for the value of its Linkend attribute. Anchor is an inline
|
|
element that may appear almost anywhere. Anchor is an empty element, with
|
|
no content.</para>
|
|
<para>Anchor can have ID, Pagenum, Remap, Role, and XRefLabel attributes,
|
|
but only the ID attribute is required. At the minimum, only the Anchor start
|
|
tag is present, with an ID.</para>
|
|
<para>When you activate a link to a location ID, the Help Viewer displays
|
|
the topic containing the ID and scrolls the window to the ID position.</para>
|
|
<sect3 id="HRDC.OrgH.div.45a">
|
|
<title>Syntax of the Anchor element</title>
|
|
<programlisting><anchor id="<symbol>id-string</symbol>"></programlisting>
|
|
</sect3>
|
|
<sect3 id="HRDC.OrgH.div.45b">
|
|
<title>Example of the Anchor element</title>
|
|
<programlisting>There is an Anchor <symbol><anchor id=“077-ch02-AN-7”></symbol> in this sentence.</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.OrgH.div.49">
|
|
<title id="HRDC.OrgH.mkr.22">Using Entities</title>
|
|
<para>An <emphasis>entity</emphasis> can represent a string of characters
|
|
or the contents of a file.</para>
|
|
<para>An <emphasis>entity declaration</emphasis> defines the entity by associating
|
|
the entity name with a specific character string or file name.</para>
|
|
<para>An <emphasis>entity reference</emphasis> is replaced by the string
|
|
or file contents when you process the help volume with the <command>dtdocbook</command> command.</para>
|
|
<para>Entities are useful for:</para>
|
|
<itemizedlist><listitem><para><emphasis>Referencing a given string of text.</emphasis> This is useful if there is some likelihood that the given string
|
|
of text may subsequently need to be changed, or if you simply don't want to
|
|
type it repeatedly.</para>
|
|
<para>Once you have declared an entity to stand for a given string of text,
|
|
each place you want the text inserted, you simply reference the entity name.
|
|
</para>
|
|
</listitem><listitem><para><emphasis>Referencing an external file, particularly
|
|
a graphics file.</emphasis> Entities provide one way of accessing graphics
|
|
files.</para>
|
|
<para>The Graphic element points via its attributes to an external file containing
|
|
graphical data.</para>
|
|
<para>The file that contains the graphical data can be specified by using
|
|
Graphic's Fileref attribute with the value of the filename, qualified by a
|
|
pathname if desired.</para>
|
|
<para>Alternatively, if the file that contains the graphical data has been
|
|
declared an entity, it can be specified by using Graphic's Entityref with
|
|
the value of the entity name.</para>
|
|
</listitem></itemizedlist>
|
|
<para>File entities are also useful for splitting your DocBook source into
|
|
multiple files. Use entity references to include other files into your master
|
|
DocBook file for processing.</para>
|
|
<sect2 id="HRDC.OrgH.div.50">
|
|
<title><emphasis>Rules for Entity Declarations</emphasis></title>
|
|
<itemizedlist><listitem><para>Entity names may contain letters (A - Z and
|
|
a - z), digits (0 - 9), the period (.), and the minus (−) sign, and
|
|
must begin with a letter.</para>
|
|
</listitem><listitem><para>Case is <emphasis>not</emphasis> significant in
|
|
entity names, but is often used to increase readability.</para>
|
|
</listitem><listitem><para>Entity names cannot be longer than 128 characters.
|
|
</para>
|
|
</listitem><listitem><para>Each entity name must be unique within a single
|
|
volume.</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.51" role="Procedure">
|
|
<title id="HRDC.OrgH.mkr.23">To Create a Text Entity</title>
|
|
<orderedlist><listitem><para>Declare an entity as follows:</para>
|
|
<programlisting><!entity <symbol>Entityname</symbol> "<symbol>text string</symbol>"></programlisting>
|
|
<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
|
|
to the entity. <emphasis>Remember, all entity declarations must be contained
|
|
in the document type declaration of your help volume.</emphasis></para>
|
|
</listitem><listitem><para>For each location where you want the <symbol>text
|
|
string</symbol> to be inserted, enter the entity reference as follows:</para>
|
|
<programlisting><symbol>&Entityname;</symbol></programlisting>
|
|
<para>The <literal>&</literal> (ampersand) and <literal>;</literal> (semicolon)
|
|
characters are required for the DocBook software to properly recognize the
|
|
entity reference.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.OrgH.div.52">
|
|
<title>Example</title>
|
|
<para>The following line declares a text entity named Assoc that contains
|
|
the string “Society of Agricultural Engineers”:</para>
|
|
<programlisting><!entity Assoc "Society of Agricultural Engineers"></programlisting>
|
|
<para>The following sentence includes a reference to the entity:</para>
|
|
<programlisting>Welcome to the &Assoc;.</programlisting>
|
|
<para>When the help volume is processed with the DocBook software, the entity
|
|
reference is replaced with the value of the entity. So, the sentence will
|
|
read:</para>
|
|
<para>Welcome to the Society of Agricultural Engineers.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.OrgH.div.53" role="Procedure">
|
|
<title id="HRDC.OrgH.mkr.24">To Create a File Entity</title>
|
|
<orderedlist><listitem><para>Declare an entity as follows:</para>
|
|
<programlisting><!entity <symbol role="Variable">Entityname</symbol> SYSTEM "<symbol role="Variable">filename</symbol>"></programlisting>
|
|
<para>Where <symbol role="Variable">Entityname</symbol> is the name of the
|
|
entity and <symbol>filename</symbol> is the name of the file. The keyword <Symbol>SYSTEM</Symbol> is required.</para>
|
|
</listitem><listitem><para>Reference the entity as follows:</para>
|
|
<itemizedlist><listitem><para>If the file is a text file, enter the following
|
|
entity reference at each location where you want the contents of the file
|
|
inserted.</para>
|
|
<programlisting><symbol>&Entityname;</symbol></programlisting>
|
|
<para>The & (ampersand) and; (semicolon) characters are required for
|
|
the DocBook software to properly recognize the entity reference.</para>
|
|
</listitem><listitem><para>If the file is a graphics file, include the name
|
|
of the entity as the value of the Entityref attribute like this:</para>
|
|
<programlisting><Graphic ID="<symbol>some-graphic-id</symbol>"Entityref=" <symbol>Entityname</symbol>"></Graphic></programlisting>
|
|
</listitem></itemizedlist>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.OrgH.div.54">
|
|
<title>Example: Text File Entities</title>
|
|
<para>Suppose you wrote the text for your help volume in three files named
|
|
<filename>file1</filename>, <filename>file2</filename>, and <filename>file3</filename>,
|
|
plus a fourth file containing your <docinfo> … </docinfo> section.
|
|
You could include them in your <symbol>volume</symbol><filename>.sgm</filename>
|
|
file like this:</para>
|
|
<programlisting><!DOCTYPE DOCBOOK [
|
|
<!entity DocInformation SYSTEM "docinfo">
|
|
<!entity MyFirstFile SYSTEM "file1">
|
|
<!entity MySecondFile SYSTEM "file2">
|
|
<!entity MyThirdFile SYSTEM "file3">
|
|
.<?Pub Caret>..
|
|
>]
|
|
|
|
<Part>
|
|
&DocInformation;
|
|
<Title>My Home Title</Title>
|
|
|
|
&MyFirstFile;
|
|
&MySecondFile;
|
|
&MyThirdFile;</programlisting>
|
|
</sect3>
|
|
<sect3 id="HRDC.OrgH.div.55">
|
|
<title>Example: A Graphic File Entity</title>
|
|
<para>Suppose a simple help volume has a Part with a Graphic in it, and graphic
|
|
data for the Graphic is stored in a file named <filename>picture.tif</filename>.
|
|
The following example shows how that Graphic would be included by using an
|
|
entity reference.</para>
|
|
<programlisting><!DOCTYPE DOCBOOK [
|
|
<!entity DocInformation SYSTEM “docinfo”>
|
|
<!entity MyPicture SYSTEM “picture.tif”>
|
|
...
|
|
]>
|
|
<Part>
|
|
&DocInformation;
|
|
<PartIntro><Title>A Simple Graphic</Title>
|
|
<Para>Welcome to my application's help volume.</Para>
|
|
</Part>
|
|
<Figure>
|
|
<Title>A Picture</Title>
|
|
<Graphic entityref="MyPicture"> </Graphic>
|
|
</Figure>
|
|
</PartIntro>
|
|
</Part>
|
|
</programlisting>
|
|
<para>The text “A Picture” is the figure's caption.</para>
|
|
<para>The markup produces this output:</para>
|
|
<graphic id="HRDC.OrgH.igrph.3" entityref="HRDC.OrgH.fig.5"></graphic>
|
|
</sect3>
|
|
<sect3 id="HRDC.OrgH.div.56">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.WrTop.mkr.23"></para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
|
|
<?Pub *0000055796>
|