Appendix C. Online Help Examples
Prev |  | Next

## Appendix C. Online Help Examples

This appendix contains listings of several online help document files.

- “A Simple Help Document”

- “Allowable Elements in a Help Document”

- “An Example of Implementing Help in an Application”

This appendix also lists the source of an example program that implements many online help features, along with its accompanying help document and helpmap file. All of these files are available online. Their locations are given before each listing.

To view these examples on your system, you must install the insight_dev product, which contains the SGIHelp library and include file, help generation tools, examples, and templates.

## A Simple Help Document

Example C-1 lists a simple help document. It's intended as a primer for writing online help documents. You can find this file online at `/usr/share/Insight/XHELP/samples/sampleDoc/sample.sgm`.

Example C-1. An Example of a Help Source File

    <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>

## Allowable Elements in a Help Document

Example C-2 lists a help document that describes the legal structures defined by the help DTD. You can find this file online at `/usr/share/Insight/XHELP/samples/XHELP_elements/XHELP_elements.sgm`.

Example C-2. A Description of the Elements Defined by the Help DTD

    <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>

## An Example of Implementing Help in an Application

This section provides a complete example of help integrated with an application.

Example C-3 lists a C program that implements a Help menu, a Help button, and context-sensitive help. You can find this file online at `/usr/share/Insight/XHELP/samples/exampleApp/exampleAppXm.c`.

Example C-4 lists the help document for `exampleAppXm`. You can find it online at `/usr/share/Insight/XHELP/samples/exampleApp/exampleAppXm.sgm`.

Example C-5 lists the helpmap file for `exampleAppXm`. You can find it online at `/usr/share/Insight/XHELP/samples/exampleApp/help/exampleAppXm.helpmap`.

Example C-3. An Example of Integrating SGIHelp With an Application

    /*_____________________________________________________________________________
     *
     * 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);
        }
    }

Example C-4. Help Source File for Example Program

    <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>

Example C-5. Helpmap for Example Program

    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

Prev | Table of Contents | Next
Appendix B. Desktop Variables |  | Appendix D. The Icon Description Language