<dochelp>
 
<!-- 
  ==================================================================
  This block denotes a SGML-style comment.
 
  For those that are unfamiliar with SGML, this sample file
  will try to cover the usage of a variety of the tags that
  are used in the XHELP DTD. The examples shown in this sample
  should be sufficient for a writer to produce a very high-quality,
  functional help document for use with an application.
 
  It is best to view this sample once it has been published,
  and then compare what you see in the viewing software to
  the actual tags displayed in this file. 
 
  Each HelpTopic block written below displays how to use the
  DTD to implement specific elements/constructs. It should be
  fairly self-explanatory.
 
  A couple of things to look for when constructing/editing
  your SGML file:
 
        o Make sure a starting element tag has an associated
          end tag! If not, then the file will not compile
          properly. This is analagous to missing a bracket
          or paranthesis in a C program!
 
        o SGML is NOT case sensitive! "HELPTOPIC" is the same
          as "helptopic", which is the same as "HelpTopic", etc.
  ==================================================================
-->
 
<HelpTopic HelpID="intro">
<Helplabel>SGI Sample SGML File</Helplabel>
<Description>
<para>This file contains examples using many of the constructs used 
in the XHELP DTD.</para>
<para>Notice that the general outline used for putting together 
a help "card" is defined by this particular SGML block. The preceding tag
defines the title that will be displayed for this card. The area you
are currently reading is a description for the feature or function you
are documenting. It is not necessary to use each of these tags, although
the "HelpTopic" tag is required.</para>
 
<para>A writer of help information may also wish to include a glossary
of terms. In that way, the documenter can tag terms within the text,
and have them display a specified definition from within the viewer. 
A sample of this is: <glossterm>sgihelp</glossterm>.</para>
<para>The actual definition for the term is found at the end of this
SGML sample.</para>
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  It's important to point out that the "HelpID" is the glue that
  binds the help text to the application, through the use of the
  provided Help API (library, header file).
  ==================================================================
-->
 
<HelpTopic HelpID="helpid_info">
<Helplabel>What is a HelpID?</Helplabel>
<Description>
<para>The HelpID attribute is used to by your application to
instruct the help server which help "card" to display. In this
case, sending the help server an ID of "helpid_info" would bring up
this particular block (or "card").</para>
<para>The other "ID" is often used as an anchor point 
(and should be used within an "ANCHOR" tag) for hypertext
links within your text. If you wish to refer to a particular card
one simply uses the ID as the anchor point for the link syntax.</para>
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  This section illustrates the simple usage of specifying a note,
  warning, tip, or caution within your help document.
  ==================================================================
-->
 
<HelpTopic HelpID="note_example">
<Helplabel><Anchor Id="AI003">Using Notes, Warnings or Tips Within a Paragraph</Helplabel>
<Description>
<para>Within the paragraph tag, there are a variety of text marking
mechanisms. Each of these delineations must appear as part of the
paragraph ("para") element.</para>
<para>This area shows the documentor how a warning, note or "tip"
can be used within a persons's help text.</para>
 
<para>
<warning><para>Be Careful. This is a warning.</para></warning>
<note><para>For your information, this is a note.</para></note>
<tip><para>When you prepare your help file, you may wish to include a tip.</para>
</tip>
<caution><para>Use a caution tag when you wish to have the user use caution!</para>
</caution>
</para>
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  This next section illustrates how to display computer output, 
  program listings, etc. within your help document.
  ==================================================================
-->
 
<HelpTopic HelpID="literal_example">
<Helplabel>Using Literals or Examples Within a Paragraph</Helplabel>
<Description>
<para>
This area shows the documentor how to implement specific examples within
their help text. It also describes how to the "literal" tag.</para>
<para>
When used within a paragraph, the LiteralLayout tag
tells the viewing software to take this next block "as is",
with all accompanying new-lines and spacing left intact.</para>
<Example>
<Title>Various Examples: ComputerOutput, LiteralLayout, ProgramListing</Title>
 
<para>
What follows is a computer output listing from when a
user typed <userInput>ls</userInput> :
<ComputerOutput>
% ls -l
total 6777
-rwxr-xr-x  1 guest  guest   29452 Mar  8 19:12 menu*
-rw-r--r--  1 guest  guest    2375 Mar  8 19:11 menu.c++
% 
</ComputerOutput>
</para>
 
<para>
Each of the subsequent three entries should be indented and on their
own line:
<LiteralLayout>
    Here is line one.
    This is line two.
    This is line three.
</LiteralLayout>
</para>
 
<para>
The following is a listing from a "C" program:
<ProgramListing>
    #include "X11/Xlib.h"
    #include "helpapi/HelpBroker.h"
 
    void main(int, char**)
    {
         /* default to the value of the DISPLAY env var */
         Display *display = XOpenDisplay(NULL);
 
         if( display ) {
               /* initialize the help server */
               SGIHelpInit(display, "MyApp", ".");
         }
         ...
    }
</ProgramListing>
</para>
</Example>
 
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  This next section illustrates how to incorporate graphics within
  your help text.
  ==================================================================
-->
 
<HelpTopic HelpID="graphic_example">
<Helplabel>Using Graphics or Figures Within Your Help Text</Helplabel>
<Description>
<para>
This area displays how a graphics or figure can be used within the flow of
your information. The following figure is in the "GIF" format:
</para>
 
<Figure ID="figure_01" Float="Yes">
    <title>A GIF Raster Image</title>
    <Graphic fileref="sample1.gif" format="GIF"></Graphic>
</Figure>
 
<para>
Currently, support is provided for <emphasis>raster</emphasis> graphics in
the GIF and TIF formats. Support is provided for <emphasis>vector</emphasis>
graphics utilizing the CGM format.
</para>
<para>
This next figure in the CGM (Computer Graphics Metafile) format:
</para>
 
<Figure ID="figure_02">
    <title>A CGM Vector Image</title>
    <Graphic fileref="sample2.cgm" format="CGM"></Graphic>
</Figure>
 
<para>
A special note that all equations are treated as inline images, as shown
here:
<equation>
    <Graphic fileref="matrix.gif" format="GIF"></Graphic>
</equation>
</para>
 
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  Hyperlinks can be a very powerful navigation mechanism!
  Liberal usage is encouraged.
  ==================================================================
-->
 
<HelpTopic HelpID="link_example">
<Helplabel>Using HyperLinks</Helplabel>
<Description>
<para>One of the most powerful capabilities of the sgihelp viewer
is the use of hyperlinks to associate like pieces of information. 
Constructing these links in SGML is trivial.</para>
<para>Notice that the "Link" element requires an attribute called
"Linkend". This defines the area (anchor) to link to. The "Linkend"
attribute points to the ID of some SGML element. In composing
help text, it is probably best to assign an ID to each "HelpTopic"
element, and use those same ID's when specifying a Link.</para>
<para>A link is defined below:</para>
<para>For more information about using Notes, refer to the area
entitled <Link Linkend="AI003">"Using Notes, Warnings or Tips
Within a Paragraph"</Link></para>
<para>Note that the "Anchor" tag can also be used within a
document to point to any level of granularity the author
wishes to link to.</para>
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  Note that there are *many* ways to specify lists. This example
  shows some commonly-used permutations.
  ==================================================================
-->
 
<HelpTopic HelpID="list_example">
<Helplabel>Using Lists Within Your Help Text</Helplabel>
<Description>
<para>This area displays how a person can author 
various types of lists within their help text.</para>
 
<para>Here is an itemized list that uses a dash to preface each item:</para>
<ItemizedList Mark="dash">
<ListItem><para>First Entry</para></ListItem>
<ListItem><para>Second Entry</para></ListItem>
<ListItem><para>Third Entry</para></ListItem>
</ItemizedList>
 
<para>Here is an itemized list that uses a bullet to preface each item:</para>
<ItemizedList Mark="bullet">
<ListItem><para>First Entry</para></ListItem>
<ListItem><para>Second Entry</para></ListItem>
</ItemizedList>
 
<para>Here is an ordered list, using standard enumeration:</para>
<OrderedList>
<ListItem><para>First Entry</para></ListItem>
<ListItem><para>Second Entry</para></ListItem>
<ListItem><para>Third Entry</para></ListItem>
</OrderedList>
 
<para>Here is another ordered list, using upper-case Roman enumeration,
showing nesting (sub-items) within the list (outline format):</para>
<OrderedList Numeration="Upperroman">
<ListItem><para>First Entry</para></ListItem>
<ListItem><para>Second Entry
    <OrderedList Numeration="Upperalpha" InheritNum="Inherit">
        <ListItem><para>First SubItem</para></ListItem>
        <ListItem><para>Second SubItem</para></ListItem>
        <ListItem><para>Third SubItem</para></ListItem>
        <ListItem><para>Fourth SubItem</para></ListItem>
    </OrderedList>
</para></ListItem>
<ListItem><para>Third Entry</para></ListItem>
</OrderedList>
 
<para>Here is a variable list of terms:</para>
<VariableList>
<VarListEntry>
<term>SGI</term>
<ListItem><para>Silicon Graphics, Inc.</para></ListItem>
</VarListEntry>
<VarListEntry>
<term>SGML</term>
<ListItem><para>A Meta-language for defining documents.</para></ListItem>
</VarListEntry>
</VariableList>
 
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  Some final examples...
  ==================================================================
-->
 
<HelpTopic HelpID="misc_example">
<Helplabel>Other Miscellaneous Textual Attributes</Helplabel>
<Description>
<para>This area displays some miscellaneous tags that can be used
within the context of your help document.</para>
 
<para>
<Comment>This is a comment that is not to be confused
with the SGML-style comment! Instead, this comment will be
parsed and carried into the text of your document. Usually it's
used in production, for specifying to someone an area of concern,
an area that needs editing, etc.
</Comment> 
</para>
 
<para>Within your text, you may wish to denote a footnote.
<Footnote id="foot1"><para>This block is a footnote!</para></Footnote>
The XHELP DTD will allow you to do that.
</para>
 
<para>
You may wish to add a copyright symbol to your text, such as:
Silicon Graphics, Inc.<trademark Class="Copyright"></trademark>
</para>
</Description>
</HelpTopic>
 
 
 
<!--
  ==================================================================
  If you wish to use/have a glossary of terms within your help text,
  it is advised to put it at the end of your help "book", as shown 
  here. NOTE: CR or other characters (#PCDATA) is NOT allowed 
  between the <Glossary> and <Title> tags! (mixed content model)
  ==================================================================
-->
 
<Glossary>
<Title>Glossary</Title>
<GlossEntry>
<GlossTerm>help</GlossTerm>
<GlossDef>
<para>To give assistance to; to get (oneself) out of a difficulty;
a source of aid.</para>
</GlossDef>
</GlossEntry>
<GlossEntry>
<GlossTerm>sgihelp</GlossTerm>
<GlossDef>
<para>This is Silicon Graphics, Inc. version of a "Xhelp" compatible
server. Through the use of an available API, and a help text
compiler, books can be constructed that can be used to render
help information for the given application.</para>
</GlossDef>
</GlossEntry></Glossary>
 
 
<!--
  ==================================================================
  Don't forget the very last ending tag...!!!
  ==================================================================
-->
 
</dochelp>

<DOCHELP>
<HELPTOPIC HelpID="">
<HELPLABEL>The Elements Alphabetized</HELPLABEL>
<DESCRIPTION>
<PARA>Emphasized entries indicate block-oriented elements.</PARA>
</DESCRIPTION></HELPTOPIC>
 
<HELPTOPIC HelpID="">
<HELPLABEL>Common Attributes </HELPLABEL>
<DESCRIPTION>
<PARA>Common attributes include ID.</PARA>
 
<PARA>ID is an identifier, which must be a
string that is unique at least within the document and
which must begin with a letter.</PARA>
</DESCRIPTION></HELPTOPIC>
 
<HELPTOPIC HelpID="">
<HELPLABEL>Other Attributes</HELPLABEL>
<DESCRIPTION>
<PARA>Certain other attributes occur regularly.  PageNum is
the number of the page on which a given element begins
or occurs in a printed book.  Label holds some text 
associated with its element that is to be output when
the document is rendered.  
Type is used with links,
as it is clear that different types of links may be
required; it duplicates the function of Role.</PARA>
 
<PARA>The Class attribute has been introduced in an attempt to
control the number of computer-specific in-line elements.
The elements that bear the Class attribute, such as 
Interface, have general
meanings that can be made more specific 
by providing a value for Class from the delimited list
for that element.  For example, for the Interface element
one may specify Menu, or Button; for the MediaLabel
element one may specify CDRom or Tape.  Each element
has its own list of permissible values for Class, and
no default is set, so you can ignore this attribute
if you wish.</PARA>
 
<PARA>An attribute that has the keyword IMPLIED bears no
processing expections if it is absent or its 
value is null.  Application designers might wish to
supply plausible defaults, but none is specified here.</PARA>
</DESCRIPTION></HELPTOPIC>
 
<HELPTOPIC HelpID="">
<HELPLABEL>cptrphrase.gp</HELPLABEL>
<DESCRIPTION>
 
<PARA>This parameter entity has been introduced to provide
some structure for in-line elements related to computers.
Its contents are:  plain text,
Anchor, Comment, Link, ComputerOutput, and UserInput.</PARA>
 
<PARA>Many of these elements now have attributes 
with delimited value lists; some former in-line elements now appear as 
values for those attributes.</PARA>
</DESCRIPTION></HELPTOPIC>
 
<HELPTOPIC HelpID="">
<HELPLABEL>"In-line" vs. "In flow"</HELPLABEL>
<DESCRIPTION>
 
<PARA>In this document, "in-line" means "occuring within a line 
of text, like a character or character string, not causing
a line break."  This term is sometimes used to 
refer to objects such as an illustration around which 
something like a paragraph is wrapped; here that circumstance
will be called "in flow."  There is no provision yet
for indicating that an object is in flow, but one could
make creative use of the Role attribute to do so.</PARA>
 
<PARA>A related point:  formal objects have titles; informal 
objects do not.  That an object is informal does not mean
that it is in-line:  these are two different 
characteristics.</PARA>
</DESCRIPTION></HELPTOPIC>
 
<HELPTOPIC HelpID="">
<HELPLABEL>List of Elements</HELPLABEL>
<DESCRIPTION>
 
<VARIABLELIST>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Actions</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A set of entries, usually in a list form, that comprise
the appropriate set of functions or steps to perform a corrective
action for a situation that is described as part of a help card.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>Anchor</TERM>
<LISTITEM>
 
<PARA>Marks a target for a Link.  
Anchor may appear almost anywhere, and has no content.
Anchor has ID, Pagenum, Remap, Role, and XRefLabel attributes;
the ID is required.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Caution</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>An admonition set off from the text;
Tip, Warning, Important, and Note all share its model.
Its contents may include paragraphs, lists, and so forth,
but not another admonition.
Caution and its sisters have common attributes.</PARA>
</LISTITEM></VARLISTENTRY> 
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Comment</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A remark made within the document file that
is intended for use during interim stages of production.
A Comment should not be displayed to the reader of the 
finished, published work.  It may appear almost anywhere, 
and may contain almost anything
below the Section level.  Note that,
unlike an SGML comment, unless you take steps
to suppress it, the Comment element
will be output by an SGML parser
or application.  You may wish to do this to display Comments
along with text during the editorial process.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>ComputerOutput</TERM>
<LISTITEM>
 
<PARA>Data presented to the user by
a computer.
It may contain elements from cptrphrase.gp,
and has common and 
MoreInfo attributes  For the MoreInfo attribute
see <EMPHASIS>Application.</EMPHASIS></PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Copyright</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>Copyright information about
a document.  It consists of one or
more Years followed by any number of Holders.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>Date</TERM>
<LISTITEM>
 
<PARA>Date of publication or revision.
It contains plain text.  (No provision
has been made for representing eras; you could include this
information along with the date data.)</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Description</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A part of a HelpTopic element.
Description may contain in-line elements.
The body may be comprised of paragraphs.
It is used to contain the body of text that
is used as a help card.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>DocHelp</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A collection of help document components.
A DocHelp entry may have a series of HelpTopic(s).
All back matter is optional, and at this time includes
a Glossary.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>DocInfo</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>Metainformation for a book
component, in which it may appear.  Only Title and AuthorGroup
are required.  DocInfo may contain, in order:  
the required Title, optional TitleAbbrev and 
Subtitle, followed by one or more 
AuthorGroups, any number of
Abstracts, an optional RevHistory, and any number of 
LegalNotices.  DocInfo has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>Emphasis</TERM>
<LISTITEM>
 
<PARA>Provided for use where you would 
traditionally use italics
or bold type to emphasize a word or phrase.
It contains plain text and 
has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Equation</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A titled mathematical equation displayed
on a line by itself, rather than in-line.  It has an optional
Title and TitleAbbrev, followed by either
an InformalEquation or a Graphic (see 
<EMPHASIS>Graphic</EMPHASIS>). 
Equation has common and Label attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Example</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>Intended for sections of program source code
that are provided as examples in the text.  
It contains a required Title and an
optional TitleAbbrev, followed by one or more block-oriented
elements in any combination.  It has common and Label
attributes.  A simple Example might contain a Title 
and a ProgramListing.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Figure</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>An illustration.  
It must have a Title, and may have a
TitleAbbrev, followed by one or more of
BlockQuote,   
InformalEquation, Graphic,
InformalTable, Link, LiteralLayout, 
OLink, ProgramListing, Screen, Synopsis, and ULink,
in any order.  Figure has common,
Label, and Float attributes; Float indicates
whether the Figure is supposed to be rendered 
where convenient (yes) or at
the place it occurs in the text (no, the default). To
reference an external file containing graphical
content use the Graphic element within Figure.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Footnote</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>The contents of a footnote, when
the note occurs outside the block-oriented element in
which the FootnoteRef occurs.  
(Compare <EMPHASIS>InlineNote.</EMPHASIS>)
The point in the text where the mark for a specific 
footnote goes is indicated by FootnoteRef.
Footnote may contain Para, SimPara, BlockQuote, InformalEquation, InformalTable,
Graphic, Synopsis, LiteralLayout, ProgramListing,
Screen, and any kind of list.
It has ID, Label, Lang, Remap, Role, and XRefLabel 
attributes; the ID attribute is required, as 
a FootnoteRef must point to it.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Glossary</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A glossary of terms.  Glossary
may occur within a Chapter, Appendix, or Preface,
or may be a book component in its own right.
It contains in order an optional DocInfo, optional
Title, and optional TitleAbbrev, followed by 
any number of block-oriented elements, followed by 
one or more GlossEntries or one or more GlossDivs.
It has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>GlossDef</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>The definition attached to a GlossTerm
in a GlossEntry.  It may contain Comments, GlossSeeAlsos,
paragraphs, and other block-oriented elements, in
any order; it has common and Subject attributes.  The Subject
attribute may hold a list of subject areas (e.g., DCE RPC 
General) as keywords.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>GlossEntry</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>An entry in a Glossary.  
It contains, in order, a required
GlossTerm, an optional Acronym,
an optional Abbrev, and either a
GlossSee or any number of GlossDefs.
It has common attributes.</PARA>
</LISTITEM></VARLISTENTRY> 
 
<VARLISTENTRY>
<TERM>GlossTerm</TERM>
<LISTITEM>
 
<PARA>A term in the text of a Chapter (for example) that is
glossed in a Glossary; also used for those terms in GlossEntries, in the
Glossary itself.  As you may not want to tag all occurrences
of these words outside of Glossaries, you might consider 
GlossTerm, when used outside of Glossaries, to be similar
to FirstTerm, except that GlossTerm may contain other 
in-line elements.  GlossTerm contains in-line elements
and has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>Graphic</TERM>
<LISTITEM>
 
<PARA>Encloses graphical data or 
points via an attribute to an external file containing such data,
and is to be rendered as an object, not in-line.
It has Format,
Fileref, Entityref, and ID attributes.
The format attribute may have the value of 
any of the formats defined at the head of the DTD,
including CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, 
EQN, FAX, FAXTILE, GIF, IGES, PIC, PS, TBL, TEX,
TIFF.</PARA>
 
<PARA>The value of Fileref should be a filename, qualified by
a pathname if desired; the value of Entityref should be that of an
external data entity.  If data is given as the 
content of Graphic, both Entityref and Fileref,
if present at all, should
be ignored, but a Format value should be supplied.
if no data is given as the content of 
Graphic and a value for Entityref
is given, Fileref, if present, should be ignored
but no Format value should be supplied.
Finally, if there is no content for Graphic and
Entityref is absent or null, Fileref must be 
given the appropriate value, and again no
Format value should be supplied.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>HelpTopic</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A part of a DocHelp document.
HelpTopic contains a HelpLabel, followed in order by
a Description, and optionally an Actions area.
HelpTopic has common and HelpId attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>HelpLabel</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>The text of a heading or the title of the HelpTopic
block-oriented element.  HelpLabel may contain
in-line elements, and has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
<VARLISTENTRY>
<TERM>InlineEquation</TERM>
<LISTITEM>
 
<PARA>An untitled mathematical equation 
occurring in-line or as the content of an Equation. 
It contains a Graphic, and has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>InlineGraphic</TERM>
<LISTITEM>
 
<PARA>Encloses graphical data or 
points via an attribute to an external file containing such data,
and is to be rendered in-line.
InlineGraphic has Format, Fileref, Entityref, and ID attributes.
The format attribute may have the value of 
any of the formats defined at the head of the DTD, under "Notations."
If it is desired to point to an external file, a filename may 
be supplied as the value of the Fileref attribute, or an
external entity name may be supplied as the value of the 
Entityref attribute.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>ItemizedList</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A list in which each item is marked with
a bullet, dash, or other dingbat (or no mark at all).  
It consists of one or more ListItems.  A ListItem in an
ItemizedList contains paragraphs and other 
block-oriented elements, which
may in turn contain other lists; an ItemizedList may be 
nested within other lists, too.  It has common attributes and
a Mark attribute.  Your application might supply the mark to be used
for an ItemizedList, but you can use this attribute to 
indicate the mark you desire to be used; there
is no fixed list of these.hfill\break <EMPHASIS>Usage Note:</EMPHASIS>  
You might want to use one of the ISO text entities
that designates an appropriate dingbat.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>Link</TERM>
<LISTITEM>
 
<PARA>A hypertext link.  At present, all
the link types represented in the DTD are
provisional.  Link is less provisional than the
others, however.  In HyTime parlance, Link is a 
clink.  It may contain in-line elements
and has Endterm, Linkend, and Type attributes.  The required
Linkend attribute specifies the target of the link, 
and the optional Endterm attribute specifies 
text that is to be fetched from elsewhere in the document
to appear in the Link.  You can also supply this text directly as
the content of the Link, <EMPHASIS>in which case the
Endterm attribute is to be ignored (new and tentative
rule for this version, comments invited)</EMPHASIS>.</PARA>
</LISTITEM></VARLISTENTRY> 
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>ListItem</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A wrapper for the elements of
items in an ItemizedList or OrderedList; it also
occurs within VarListEntry in VariableList.
It may contain just about anything except Sects and book components.
It has common attributes and an Override attribute, which
may have any of the values of ItemizedList's
Mark attribute; use Override to override the mark
set at the ItemizedList level, when you desire to create
ItemizedLists with varying marks.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>LiteralLayout</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>The wrapper for lines set off from
the main text that are not tagged as Screens, Examples,
or ProgramListing, in which line breaks and leading
white space are to be regarded as significant.
It contains in-line elements, and has common 
and Width attributes, for specifying a number representing
the maximum width of the contents.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Note</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A message to the user, set off from the text.
See <EMPHASIS>Caution.</EMPHASIS></PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>OrderedList</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A numbered or lettered list, consisting of
ListItems.  A ListItem in an
OrderedList contains paragraphs and other 
block-oriented elements, which
may in turn contain other lists; an OrderedList may be 
nested within other lists, too. 
OrderedList has common attributes, along with 
a Numeration attribute, which
may have the value Arabic, Upperalpha, Loweralpha,
Upperroman, or Lowerroman.  The default is Arabic (1, 2, 3, . . .).  
It has an InheritNum attribute, for which the value Inherit specifies for a
nested list that the numbering of ListItems should include the 
number of the item within which they are nested (2a, 2b, etc.,
rather than a, b, etc.); the default value is Ignore.  
It has a Continuation attribute, with values 
Continues or Restarts (the default), which may be used to
indicate whether the numbering of a list begins afresh (default)
or continues that of the immediately preceding list (Continues).  
You need supply the Continuation attribute only
if your list continues the numbering of the preceding list.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Para</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A paragraph.  A Para may not
have a Title:  to attach a Title to a Para use FormalPara.  Para
may contain any in-line element and almost
any block-oriented element.  Abstract, AuthorBlurb, Caution, 
Important, Note, and Warning are excluded, as are Sects and higher-level 
elements.  Para has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>ProgramListing</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A listing of a program. 
Line breaks and leading 
white space are significant in a ProgramListing, which  
may contain in-line elements, including LineAnnotations.
(LineAnnotations are a document author's 
comments on the code, not the comments written
into the code itself by the code's author.)
ProgramListing has common and Width attributes, the 
latter for specifying a number representing the maximum 
width of the contents.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>Term</TERM>
<LISTITEM>
 
<PARA>The hanging term attached to a ListItem 
within a VarListEntry in a
VariableList; visually, a VariableList 
is a set of Terms with attached items such as paragraphs.  Each
ListItem may be associated with a set of Terms.  Term may contain
in-line elements. It has common attributes.</PARA>
</LISTITEM></VARLISTENTRY> 
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Tip</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A suggestion to the user, set off from 
the text. See <EMPHASIS>Caution.</EMPHASIS></PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Title</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>The text of a heading or the title of a
block-oriented element.  Title may contain
in-line elements, and has common and PageNum attributes.</PARA>
</LISTITEM></VARLISTENTRY> 
 
<VARLISTENTRY>
<TERM>Trademark</TERM>
<LISTITEM>
 
<PARA>A trademark.  It may contain members of cptrphrase.gp,
and has common and Class attributes.
Class may have the values Service, Trade, Registered,
or Copyright; the default is Trade.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>UserInput</TERM>
<LISTITEM>
 
<PARA>Data entered by the user.  
It may contain elements from cptrphrase.gp,
and has common and MoreInfo attributes.  For the MoreInfo attribute 
see <EMPHASIS>Application.</EMPHASIS></PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>VariableList</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>An optionally 
titled list of VarListEntries, which are
composed of sets of one or more Terms with associated
ListItems; ListItems contain paragraphs and other block-oriented
elements in any order.  Inclusions 
are as for OrderedList (see <EMPHASIS>OrderedList</EMPHASIS>).  
VariableList has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>VarListEntry</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>A component of VariableList (see 
<EMPHASIS>VariableList</EMPHASIS>).  It has common attributes.</PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>
<EMPHASIS>Warning</EMPHASIS></TERM>
<LISTITEM>
 
<PARA>An admonition set off from the text.
See <EMPHASIS>Caution.</EMPHASIS></PARA>
</LISTITEM></VARLISTENTRY>
 
<VARLISTENTRY>
<TERM>XRef</TERM>
<LISTITEM>
 
<PARA>Cross reference link to another part of the document.  
It has Linkend and Endterm attributes, just like Link,
but like Anchor, it may have no content.
XRef must have a Linkend, but the Endterm is optional.
If it is used, the content of the element it points
to is displayed as the text of the cross reference;
if it is absent, the XRefLabel of the cross-referenced
object is displayed.  To include in the cross reference
generated text associated with the object referred to,
use your application's style sheet.  See <EMPHASIS>Link.</EMPHASIS></PARA>
</LISTITEM></VARLISTENTRY>
 
</VARIABLELIST>
</DESCRIPTION></HELPTOPIC>
</DOCHELP>

/*_____________________________________________________________________________
 *
 * File:         exampleAppXm.c
 *
 * Date:         3/25/94
 *
 * Compile with: cc -o exampleAppXm exampleAppXm.c -lhelpmsg -lXm -lXt -lX11
 *
 * Purpose:      An simple example program that shows how to use the SGI
 *               Help system from a Motif application.
 *
 *               This program displays a few buttons on a bulletin board 
 *               alongwith a help menu. The use of context sensitive help
 *               is also demonstrated.
 *_____________________________________________________________________________
 */
 
/*
 * standard include files
 */
 
#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <X11/cursorfont.h>
#include <Xm/Xm.h>
#include <Xm/Label.h>
#include <Xm/PushB.h>
#include <Xm/Form.h>
#include <Xm/MessageB.h>
#include <Xm/MainW.h>
#include <Xm/RowColumn.h>
#include <Xm/CascadeB.h>
#include <Xm/Separator.h>
 
/*
 * include for for calling/using SGIHelp
 */
 
#include <helpapi/HelpBroker.h>
 
 
/*
 * forward declarations of functions
 */
 
Widget initMotif(int          *argcP,            /* Initializes motif and    */
                 char         *argv[],           /* and returns the top level*/
                 XtAppContext *app_contextP,     /* shell.                   */
                 Display      **displayP);             
 
void createInterface(Widget parent);             /*creates the main window,  */
                                                 /*menus, and the buttons    */
                                                 /*on the main window        */
 
void clickForHelpCB();                           /*callbacks for each of     */
void overviewCB();                               /*the help menu's           */
void taskCB();
void indexCB();
void keysAndShortcutsCB();
void productInfoCB();
 
void infoDialogCB();
 
 
Widget _mainWindow, _infoDialog=NULL;
 
 
 
/*_____________________________________________________________________________
 *
 * main()
 *_____________________________________________________________________________
 */
 
main(int argc, char *argv[])
{
    Display      *display;
    XtAppContext app_context;
    Widget       toplevel;
    
    toplevel = initMotif (&argc,argv,&app_context,&display);
 
    createInterface(toplevel);
 
    XtRealizeWidget(toplevel);
 
    XtAppMainLoop(app_context);
}
 
/*_____________________________________________________________________________
 *
 * Function: initMotif()
 *
 * Purpose:  Initializes Motif and creates a top level shell.
 *           Returns the toplevel shell.
 *
 *           Makes the call to initialize variables for the SGIHelp
 *           interface...note that it does not *start* the sgihelp
 *           process. That is done when a request for help is made,
 *           if and only if the sgihelp process is not already
 *           running.
 *
 *_____________________________________________________________________________
 */
Widget initMotif(int *argcP,char *argv[],XtAppContext *app_contextP,
                 Display **displayP)
{
    Widget toplevel;
 
    XtToolkitInitialize();
    *app_contextP = XtCreateApplicationContext();
    *displayP     = XtOpenDisplay(*app_contextP,NULL,"exampleAppXm",
                                  "exampleAppXmClass",NULL,
                                  0,argcP, argv);
 
    if (*displayP == NULL) {
        fprintf (stderr,"Could not open display.\n");
        fprintf (stderr,"Check your DISPLAY environment variable.\n");
        fprintf (stderr,"Exiting...\n");
        exit(-1);
    }
    
    toplevel = XtAppCreateShell("exampleAppXm", NULL, 
                                applicationShellWidgetClass,
                                *displayP, NULL,0);
    
/* 
 * initialize variables for SGIHelp 
 */
    SGIHelpInit(*displayP, "exampleAppXm", ".");
 
    return (toplevel);   
}
 
 
/*_____________________________________________________________________________
 *
 * Function:   createInterface()
 *_____________________________________________________________________________
 */
void createInterface(Widget parent)
{
    Arg    args[10];
    int    i;
    Widget baseForm;
    Widget menuBar;
    Widget demoLabel, demoButton;
    Widget pulldown1,pulldown2, cascade1, cascade2;
    Widget menuButtons[6];   /*we will create at max 6 buttons on a menu*/
    XmString xmStr;
 
/*
 * mainWindow is an XmMainWindow
 * on which the whole interface is built
 */
    i=0;
    _mainWindow = XmCreateMainWindow(parent,"mainWindow",args,i);
    XtManageChild(_mainWindow);
 
/*
 * baseForm is the workArea for the
 * mainWindow above.
 */
    i=0;
    XtSetArg (args[i],XmNwidth,400);i++;
    XtSetArg (args[i],XmNheight,300);i++;
    XtSetArg (args[i],XmNverticalSpacing,40);i++;
    baseForm = XmCreateForm(_mainWindow,"baseForm",args,i);
    XtManageChild(baseForm);
 
/*
 * On this bulletin board, put a label and a button
 * for demonstrating callbacks and context sensitive
 * help.
 */
    i=0;
    xmStr = XmStringCreateSimple("SGI Help!");
    XtSetArg (args[i],XmNlabelString,xmStr);i++;
    XtSetArg (args[i],XmNtopAttachment,XmATTACH_FORM);i++;
    XtSetArg (args[i],XmNrightAttachment,XmATTACH_FORM);i++;
    XtSetArg (args[i],XmNleftAttachment,XmATTACH_FORM);i++;
    XtSetArg (args[i],XmNalignment,XmALIGNMENT_CENTER);i++;
    demoLabel = XmCreateLabel(baseForm,"sgiHelpLabel",args,i);
    XtManageChild(demoLabel);
    XmStringFree(xmStr);
    
    i=0;
    xmStr = XmStringCreateSimple("Click Here For Help");
    XtSetArg (args[i],XmNlabelString,xmStr);i++;
    XtSetArg (args[i],XmNrightAttachment,XmATTACH_FORM);i++;
    XtSetArg (args[i],XmNbottomAttachment,XmATTACH_FORM);i++;
    demoButton = XmCreatePushButton(baseForm,"sgiHelpPushButton",args,i);
    XtManageChild(demoButton);
    XmStringFree(xmStr);
    XtAddCallback(demoButton,XmNactivateCallback,taskCB,NULL);
 
/*
 * build a pulldown menu system, including the "help" menu
 */
    menuBar   = XmCreateMenuBar(_mainWindow,"menuBar",NULL,0);
    XtManageChild(menuBar);
 
    pulldown1 = XmCreatePulldownMenu(menuBar,"pulldown1",NULL,0);
    pulldown2 = XmCreatePulldownMenu(menuBar,"pulldown2",NULL,0);
 
    i=0;
    XtSetArg (args[i],XmNsubMenuId,pulldown1);i++;
    cascade1 = XmCreateCascadeButton(menuBar,"File",args,i);
    XtManageChild(cascade1);
 
    i=0;
    XtSetArg (args[i],XmNsubMenuId,pulldown2);i++;
    cascade2 = XmCreateCascadeButton(menuBar,"Help",args,i);
    XtManageChild(cascade2);
 
/*
 * Declare this to be the Help menu
 */
    i=0;
    XtSetArg (args[i],XmNmenuHelpWidget,cascade2);i++;
    XtSetValues(menuBar,args,i);
 
    menuButtons[0] = XmCreatePushButton(pulldown1,"Exit",NULL,0);
    XtManageChildren(menuButtons,1);
    XtAddCallback(menuButtons[0],XmNactivateCallback,(XtCallbackProc)exit,0);
 
    menuButtons[0] = XmCreatePushButton(pulldown2,"Click for Help",NULL,0);
    menuButtons[1] = XmCreatePushButton(pulldown2,"Overview",NULL,0);
    XtManageChild( XmCreateSeparator(pulldown2, "separator1",NULL,0) );
    menuButtons[2] = XmCreatePushButton(pulldown2,"Sample Help Task",NULL,0);
    XtManageChild( XmCreateSeparator(pulldown2, "separator2",NULL,0) );
    menuButtons[3] = XmCreatePushButton(pulldown2,"Index",NULL,0);
    menuButtons[4] = XmCreatePushButton(pulldown2,"Keys and Shortcuts",NULL,0);
    XtManageChild( XmCreateSeparator(pulldown2, "separator3",NULL,0) );
    menuButtons[5] = XmCreatePushButton(pulldown2,"Product Information",NULL,0);
 
    XtManageChildren(menuButtons,6);
 
/*
 * add callbacks to each of the help menu buttons
 */
    XtAddCallback(menuButtons[0],XmNactivateCallback,clickForHelpCB,NULL);
    XtAddCallback(menuButtons[1],XmNactivateCallback,overviewCB,NULL);
    XtAddCallback(menuButtons[2],XmNactivateCallback,taskCB,NULL);
    XtAddCallback(menuButtons[3],XmNactivateCallback,indexCB,NULL);
    XtAddCallback(menuButtons[4],XmNactivateCallback,keysAndShortcutsCB,NULL);
    XtAddCallback(menuButtons[5],XmNactivateCallback,productInfoCB,NULL);
 
/*
 * set the bulletin board and menubar into
 * the main Window.
 */
    XmMainWindowSetAreas(_mainWindow,menuBar,NULL,NULL,NULL,baseForm);
}
 
 
/*_____________________________________________________________________________
 *
 * void clickForHelpCB()
 *
 * Purpose:  Provides context-sensitivity within an application;
 *           makes a request to the sgihelp process.
 *
 *_____________________________________________________________________________
 */
 
void clickForHelpCB(Widget wid, XtPointer clientData, XtPointer callData)
{
     static Cursor cursor = NULL;
     static char path[512], tmp[512];
     Widget shell, result, w;
  
     strcpy(path, "");
     strcpy(tmp,  "");
 
/* 
 * create a question-mark cursor 
 */
     if(!cursor)
         cursor = XCreateFontCursor(XtDisplay(wid), XC_question_arrow);
 
     XmUpdateDisplay(_mainWindow);
 
/* 
 * get the top-level shell for the window 
 */
     shell = _mainWindow;
     while (shell && !XtIsShell(shell)) {
            shell = XtParent(shell);
     }
 
/*
 * modal interface for selection of a component;
 * returns the widget or gadget that contains the pointer
 */
     result = XmTrackingLocate(shell, cursor, FALSE);
 
     if( result ) {
         w = result;
 
/* 
 * get the widget hierarchy; separate with a '.';
 * this also puts them in top-down vs. bottom-up order.
 */
         do {
              if( XtName(w) ) {
                  strcpy(path, XtName(w));
 
                  if( strlen(tmp) > 0 ) {
                      strcat(path, ".");
                      strcat(path, tmp);
                  }
 
                  strcpy(tmp, path);
              }
 
              w = XtParent(w);
         } while (w != NULL && w != shell);
 
         /*
          * send msg to the help server-widget hierarchy;
          *      OR
          * provide a mapping to produce the key to be used
          *
          * In this case, we'll let the sgihelp process do
          * the mapping for us, with the use of a helpmap file
          *
          * Note that parameter 2, the book name, can be found
          * from the helpmap file as well. The developer need
          * not hard-code it, if a helpmap file is present for
          * the application. 
          *
          */
          if( strlen(path) > 0 ) {
                SGIHelpMsg(path, NULL, NULL);
          }
     }
}
  
 
/*_____________________________________________________________________________
 *
 * void overviewCB()
 *_____________________________________________________________________________
 */
void overviewCB()
{
 
/*
 * Using the mapping file allows us to specify
 * a "Overview" help card for each window in
 * our application. In this case, we will point
 * to a specific one. Note that the book name is
 * specified, but not necessary if a helpmap file
 * exists for this application.
 */
        SGIHelpMsg("overview", "exampleAppXmHelp", NULL);
}
 
 
/*_____________________________________________________________________________
 *
 * void indexCB()
 *_____________________________________________________________________________
 */
void indexCB()
{
 
/*
 * For the index window to work for this application,
 * a helpmap file MUST be present!
 */
        SGIHelpIndexMsg("index", NULL);
}
 
 
/*_____________________________________________________________________________
 *
 * void taskCB()
 *_____________________________________________________________________________
 */
void taskCB()
{
 
/*
 * For the task found in the help menu or a pushbutton, we
 * use a specific key/book combination.
 */
        SGIHelpMsg("help_task", "exampleAppXmHelp", NULL);
}
 
 
/*_____________________________________________________________________________
 *
 * void keysAndShortcutsCB()
 *_____________________________________________________________________________
 */
void keysAndShortcutsCB()
{
 
/*
 * This would point to the help card that contains
 * information about the use of keys/accelerators, etc.
 * for your application.
 */
        SGIHelpMsg("keys", "exampleAppXmHelp", NULL);
}
 
 
/*_____________________________________________________________________________
 *
 * void productInfoCB()
 *_____________________________________________________________________________
 */
void productInfoCB()
{
 
/*
 * Pops up a dialog showing product version information.
 *
 * This area has nothing to do with SGIHelp, but is included
 * for completeness.
 */
 
  void     buildInfoDialog();
 
  XmString xmStr;
  Arg      args[10];
  int      i;
 
    if( _infoDialog == NULL ) {
        buildInfoDialog();
        XtRealizeWidget( _infoDialog );
    }
 
    xmStr=XmStringCreateSimple("Example Motif App Using SGIHelp version 1.0");
    i=0;
    XtSetArg (args[i],XmNmessageString,xmStr);i++;
    XtSetValues(_infoDialog, args, i);
    XmStringFree(xmStr);
 
    XtManageChild(_infoDialog);
}
 
 
void buildInfoDialog()
{
  Arg    args[10];
  int    i;
 
/*
 * Build the informational dialog to display the version info
 */
    i=0;
    XtSetArg (args[i],XmNautoUnmanage,True);i++;
    XtSetArg (args[i],XmNdialogType,XmDIALOG_WORKING);i++;
    XtSetArg (args[i],XmNdialogStyle,XmDIALOG_APPLICATION_MODAL);i++;
    _infoDialog = XmCreateInformationDialog(_mainWindow,"infoDialog",args,i);
 
    XtAddCallback(_infoDialog, XmNokCallback, infoDialogCB, NULL);
 
    XtUnmanageChild(XmMessageBoxGetChild(_infoDialog, XmDIALOG_CANCEL_BUTTON));
    XtUnmanageChild(XmMessageBoxGetChild(_infoDialog, XmDIALOG_HELP_BUTTON));
}
 
 
void infoDialogCB()
{
    if ( _infoDialog ) {
         XtUnmanageChild(_infoDialog);
 
         /* Explicitly set the input focus */
         XSetInputFocus(XtDisplay(_mainWindow), PointerRoot, 
                        RevertToParent, CurrentTime);
    }
}

<dochelp>
 
<HelpTopic HelpID="overview">
<Helplabel>Example Motif Application Using SGIHelp</Helplabel>
<Description>
<para>
This application is intended to show the developer how
the <glossterm>SGIHelp</glossterm> system can work for you. 
It displays (in the included
sample code, exampleAppXm.c) usage of various widgets, a sample 
help menu, full-context-sensitivity, and calls to 
the <glossterm>SGIHelp</glossterm> server process via the API.
</para>
 
<Figure ID="figure_01">
    <title>exampleAppXm Main Window</title>
    <Graphic fileref="mainwnd.gif" format="GIF"></Graphic>
</Figure>
 
<para>
The application itself is very simple, composed of
a <Link Linkend="ID002">File menu,</Link> 
a <Link Linkend="ID003">Help menu,</Link> 
a <Link Linkend="ID005">Pushbutton,</Link> 
and a <Link Linkend="ID004">Label</Link>.
The user can choose items from the 
<Link Linkend="ID003">Help menu</Link> to
contact the <glossterm>SGIHelp</glossterm> server process to 
cause different help cards to be rendered.
</para>
<para>To quit the application, use the "Exit" command
found under the <Link Linkend="ID002">File menu</Link>.
</para>
</Description>
</HelpTopic>
 
 
<HelpTopic HelpID="file_menu">
<Helplabel><Anchor Id="ID002">The File Menu</Helplabel>
<Description>
<para>The following items (and their functions) are part of 
the File menu:</para>
<VariableList>
<VarListEntry>
<term>Exit</term>
<ListItem><para>Used to quit the exampleAppXm application.</para></listitem>
</VarListEntry>
</VariableList>
</Description>
</HelpTopic>
 
 
<HelpTopic HelpID="help_menu">
<Helplabel><Anchor Id="ID003">The Help Menu</Helplabel>
<Description>
<para>The following items (and their functions) are part of 
the Help menu:</para>
<VariableList>
<VarListEntry>
<term>Click for Help</term>
<ListItem><para>Used to put the application in context sensitive mode.
Will cause the cursor to turn into a "?" at which point the user can
click on any entry in the application's window to obtain help.</para></listitem>
</VarListEntry>
<VarListEntry>
<term>Overview</term>
<ListItem><para>Used to display a help overview card for the current 
window.</para></listitem>
</VarListEntry>
<VarListEntry>
<term>Index</term>
<ListItem><para>Used to display from SGIHelp an Index of help topics for 
the given application.</para></listitem>
</VarListEntry>
<VarListEntry>
<term>Keys & Shortcuts</term>
<ListItem><para>Used to display a help card that describes any special
key combinations this application uses.</para></listitem>
</VarListEntry>
<VarListEntry>
<term>Product Info</term>
<ListItem><para>Pops up a dialog that displays to the user any version or
copyright information for this application.</para></listitem>
</VarListEntry>
</VariableList>
<para>To access any menu items, click on the menu item
that is a part of the menubar. When the menu pops-up,
highlight the desired item, and release the mouse button.
</para>
</Description>
</HelpTopic>
 
 
<HelpTopic HelpID="help_label">
<Helplabel><Anchor Id="ID004">A Label</Helplabel>
<Description>
<para>You have clicked on a Label. It simply displays information
to the user and serves no other useful pourpose.</para>
<tip><para>Basically, a label is useless. For information only.</para></tip>
</Description>
</HelpTopic>
 
 
<HelpTopic HelpID="help_button">
<Helplabel><Anchor Id="ID005">A Pushbutton</Helplabel>
<Description>
<para>You have clicked on a Pushbutton. A pushbutton, when
clicked, will activate some type of command within the application.</para> 
</Description>
</HelpTopic>
 
 
<HelpTopic HelpID="keys">
<Helplabel><Anchor Id="ID006">Keys and Shortcuts</Helplabel>
<Description>
<para>This card displays all known keys and shortcuts for this
application.</para> 
<warning><para>This application has no shortcuts.</para></warning>
</Description>
</HelpTopic>
 
 
<HelpTopic HelpID="help_task">
<Helplabel><Anchor Id="ID007">A Sample Help Task</Helplabel>
<Description>
<para>
When creating your application and help text, you may wish
to highlight certain common tasks. This help card was
displayed from either a menu item or a pushbutton.
</para>
<para>
To perform such an operation within your code, the
associated callback that contacts the <glossterm>SGIHelp</glossterm> server 
can be constructed as shown below.</para>
<Example>
<Title>Sample Help Task Callback</Title>
 
<para>
The following is a listing derived from a "C" program:
<ProgramListing>
    /* create menu items, pushbuttons, etc. */
 
    void taskCB()
    {
 
    /*
     * For the task found in the help menu,
     * we'll use a specific key/book 
     * combination.
     */
        SGIHelpMsg("key", "myBook", NULL);
    }
</ProgramListing>
</para>
</Example>
<para>It's relatively simple process to integrate help
into your application. In fact, the <glossterm>SGIHelp</glossterm>
process only requires <emphasis>two</emphasis> function calls.
</para>
</Description>
</HelpTopic>
 
 
<Glossary>
<Title>Glossary</Title>
 
<GlossEntry>
<GlossTerm>SGIHelp</GlossTerm>
<GlossDef>
<para>This is Silicon Graphics, Inc. version of a "Xhelp" compatible
server. Through the use of an available API, and a help text
compiler, books can be constructed that can be used to render
help information for the given application.</para>
</GlossDef>
</GlossEntry>
 
</Glossary>
 
 
</dochelp>

1;exampleAppXmHelp;Example Motif App Overview;0;overview;exampleAppXm.overview;exampleAppXm.mainWindow.baseForm;exampleAppXm.mainWindow.menuBar;exampleAppXm.mainWindow
2;exampleAppXmHelp;File Menu;1;file_menu;exampleAppXm.mainWindow.menuBar.File
2;exampleAppXmHelp;Help Menu;1;help_menu;exampleAppXm.mainWindow.menuBar.Help
2;exampleAppXmHelp;A Label Entry;1;help_label;exampleAppXm.mainWindow.baseForm.sgiHelpLabel
2;exampleAppXmHelp;A Pushbutton Entry;1;help_button;exampleAppXm.mainWindow.baseForm.sgiHelpPushButton
2;exampleAppXmHelp;Keys and Shortcuts;0;keys;exampleAppXm.keys
2;exampleAppXmHelp;A Sample Help Task;0;help_task;exampleAppXm.exampleAppXm