329 lines
17 KiB
Plaintext
329 lines
17 KiB
Plaintext
<!-- $XConsortium: ch11.sgm /main/10 1996/09/08 19:40:53 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<chapter id="HRDC.H4Hlp.div.1">
|
|
<title id="HRDC.H4Hlp.mkr.1">Providing Help on Help</title>
|
|
<para>This chapter explains how to incorporate a help volume into your application
|
|
that describes the features of the Help System and how to use them. This
|
|
help volume provides help on using the Help dialog boxes.</para>
|
|
<informaltable id="HRDC.H4Hlp.itbl.1" frame="All">
|
|
<tgroup cols="1">
|
|
<colspec colname="1" colwidth="4.0 in">
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Accessing Help on Help in an Application236'--><xref
|
|
role="JumpText" linkend="HRDC.H4Hlp.mkr.2"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Set the helpOnHelpVolume Resource237'--><xref
|
|
role="JumpText" linkend="HRDC.H4Hlp.mkr.3"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Provide a Using Help Command237'--><xref
|
|
role="JumpText" linkend="HRDC.H4Hlp.mkr.4"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Display Help on Help238'--><xref
|
|
role="JumpText" linkend="HRDC.H4Hlp.mkr.5"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Writing Your Own Help on Help Volume239'--><xref
|
|
role="JumpText" linkend="HRDC.H4Hlp.mkr.6"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Copy the Help4Help Source Files241'--><xref
|
|
role="JumpText" linkend="HRDC.H4Hlp.mkr.7"></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<sect1 id="HRDC.H4Hlp.div.2">
|
|
<title>Providing Help on Help</title>
|
|
<para>Help on help tells users how to use the Help System. Specifically, it
|
|
describes such tasks as using hyperlinks, navigating topics, using the index,
|
|
and printing help topics. Normally, help on help is supplied as an individual
|
|
help volume named Help4Help.</para>
|
|
<para>The Help4Help volume and its source files are included in the Developer's
|
|
Toolkit. You can use the default volume “as is,” or modify it
|
|
for your application's design.</para>
|
|
<sect2 id="HRDC.H4Hlp.div.3">
|
|
<title>For Application Help</title>
|
|
<para>If you are writing application-specific help, there are two ways to
|
|
ensure that your application has help on help for its own help dialogs:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Rely on the desktop's
|
|
help on help volume.</emphasis> For example, on workstations running the
|
|
desktop, the standard Help4Help volume is installed.</para>
|
|
</listitem><listitem><para><emphasis>Supply your own help on help volume.</emphasis> The DocBook source files for the Help4Help volume are provided
|
|
in the <filename>/usr/dt/dthelp/help4help/C</filename> directory. You run
|
|
DocBook in this directory to create the run-time help file. Graphics files
|
|
used in the help on help volume are stored in the <filename>graphics</filename>
|
|
subdirectory.</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.H4Hlp.div.4">
|
|
<title>For Standalone Help</title>
|
|
<para>If you are writing standalone help, you are probably relying on the
|
|
Helpview program already being installed and ready to use. If this is the
|
|
case, you don't have to worry about help on help because Helpview accesses
|
|
the standard Help4Help volume by default.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.H4Hlp.div.5">
|
|
<title>How Help on Help Is Found</title>
|
|
<para>Each application that uses the Help System (including Helpview) has
|
|
a <systemitem class="resource">helpOnHelpVolume</systemitem> resource that
|
|
identifies a help volume to be accessed for help on help topics. For Helpview,
|
|
this resource is set as follows:</para>
|
|
<programlisting>DtHelpview*helpOnHelpVolume: Help4Help</programlisting>
|
|
<para>If you provide your own help on help volume, be sure to give it a unique
|
|
name so it doesn't conflict with another help on help volume that may be installed
|
|
on the system.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.H4Hlp.div.6">
|
|
<title id="HRDC.H4Hlp.mkr.2">Accessing Help on Help in an Application</title>
|
|
<para>Your application should do the following to support help on help:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Set the <systemitem class="resource">helpOnHelpVolume</systemitem> resource to identify the help volume you want
|
|
to access.</para>
|
|
</listitem><listitem><para>Add a <command>Using Help</command> command to
|
|
the application's Help menu.</para>
|
|
</listitem></itemizedlist>
|
|
<sect2 id="HRDC.H4Hlp.div.7" role="Procedure">
|
|
<title id="HRDC.H4Hlp.mkr.3">To Set the helpOnHelpVolume Resource</title>
|
|
<orderedlist><listitem><para>Add a line to your application's application-defaults
|
|
file like this:</para>
|
|
<para><symbol role="Variable">App-class</symbol>* <systemitem class="resource">helpOnHelpVolume</systemitem>: <symbol role="Variable">volume</symbol></para>
|
|
<para>Where <symbol role="Variable">App-class</symbol> is the application's
|
|
class name and <symbol role="Variable">volume</symbol> is the name of the
|
|
help on help volume you want to access.</para>
|
|
<para><emphasis>Or,</emphasis> within your application, set the <systemitem class="resource">helpOnHelpVolume</systemitem> resource for each help dialog
|
|
you create.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.H4Hlp.div.8">
|
|
<title>Examples</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para>This line in <filename>dthelpview's</filename> application-defaults file (<command>DtHelpview</command>) specifies
|
|
the help on help volume:</para>
|
|
<programlisting>DtHelpview*helpOnHelpVolume: Help4Help</programlisting>
|
|
</listitem><listitem><para>To specify the help on help volume when creating
|
|
a help dialog, add it to the argument list passed to the create function
|
|
as shown here:</para>
|
|
<programlisting>ac = 0;
|
|
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
|
|
XtSetArg (al[ac], DtNhelpOnHelpVolume, "Help4Help"); ac++;
|
|
helpDialog = DtCreateHelpDialog (parent, "helpDialog", al, ac);</programlisting>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.H4Hlp.div.9" role="Procedure">
|
|
<title id="HRDC.H4Hlp.mkr.4">To Provide a Using Help Command</title>
|
|
<orderedlist><listitem><para>Add to your Help menu a button labeled <literal>Using Help</literal>. Also add the necessary activate callback to call your <function>HelpRequestCB()</function> function.</para>
|
|
</listitem><listitem><para>Add support to your <function>HelpRequestCB()</function>
|
|
function to display help on help. Specifically:</para>
|
|
<itemizedlist><listitem><para>Create a quick help dialog.</para>
|
|
</listitem><listitem><para>Set the dialog's title to Help On Help.</para>
|
|
</listitem><listitem><para>Display the home topic of the help on help volume.
|
|
</para>
|
|
</listitem><listitem><para>Manage the quick help dialog.</para>
|
|
</listitem></itemizedlist>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.H4Hlp.div.10">
|
|
<title>Example</title>
|
|
<para>The following lines create a menu button labeled <literal>Using Help…</literal> that calls the <function>HelpRequestCB()</function> function.
|
|
</para>
|
|
<programlisting>/* <emphasis>Create the "Using Help ..." button.</emphasis> */
|
|
labelStr = XmStringCreateLtoR ("Using Help ...",
|
|
XmSTRING_DEFAULT_CHARSET);
|
|
ac = 0;
|
|
XtSetArg (al[ac], XmNlabelString, labelStr); ac++;
|
|
button = XmCreatePushButtonGadget (parent, "usingHelpButton", al,
|
|
ac);
|
|
XtManageChild (button);
|
|
XmStringFree (labelStr);
|
|
/* <emphasis>Add a callback to the button.</emphasis> */
|
|
XtAddCallback (button,XmNactivateCallback,HelpRequestCB,
|
|
USING_HELP);</programlisting>
|
|
<para><systemitem class="constant">USING_HELP</systemitem> is the client data
|
|
passed to the <function>HelpRequestCB()</function> function when the menu
|
|
button is chosen by the user. Presumably it has been defined somewhere in
|
|
the application (perhaps in a <filename>Help.h</filename> file) as a unique
|
|
integer:</para>
|
|
<programlisting>#define USING_HELP 47</programlisting>
|
|
<para>To see how the <function>HelpRequestCB()</function> function handles
|
|
the <systemitem class="constant">USING_HELP</systemitem> case, see the example
|
|
in the next section, “To Display Help on Help.”</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.H4Hlp.div.11" role="Procedure">
|
|
<title id="HRDC.H4Hlp.mkr.5">To Display Help on Help</title>
|
|
<orderedlist><listitem><para>Create a quick help dialog (or retrieve one from
|
|
your cache).</para>
|
|
</listitem><listitem><para>Display in the dialog the home topic of your help
|
|
on help volume.</para>
|
|
</listitem></orderedlist>
|
|
<para>Help on help can be displayed in a general help window, but a quick
|
|
help dialog is recommended because its user interface is simpler and less
|
|
intimidating to the new users who commonly need help on help.</para>
|
|
<sect3 id="HRDC.H4Hlp.div.12">
|
|
<title>Example</title>
|
|
<para>The following program segment is part of a <function>HelpRequestCB()</function> function. Presumably, the <systemitem class="constant">USING_HELP</systemitem> constant is passed to the function because the user chose Using
|
|
Help from the application's Help menu or chose the Help button in a quick
|
|
help dialog.</para>
|
|
<para>This example assumes that the application never creates more than one
|
|
Help On Help dialog and maintains its widget ID in a variable called <symbol role="Variable">onHelpDialog</symbol>.</para>
|
|
<programlisting>case USING_HELP:
|
|
if (onHelpDialog == (Widget)NULL)
|
|
{
|
|
/* <emphasis>Get a quick help dialog for use as the "help on help" dialog.</emphasis> */
|
|
onHelpDialog = FetchHelpDialog (True);
|
|
if (onHelpDialog == (Widget)NULL)
|
|
/* <emphasis>We didn't get a dialog! Add your error handling code here.</emphasis> */
|
|
}
|
|
/* <emphasis>Set the proper volume and ID to display the home topic of the help on help volume. Also, set the dialog's title.</emphasis> */
|
|
ac = 0; XtSetArg (al[ac], XmNtitle, "Help On Help"); ac++;
|
|
XtSetArg (al[ac], XmNhelpType, DT_HELP_TYPE_TOPIC); ac++;
|
|
XtSetArg (al[ac], XmNhelpVolume, "Help4Help"); ac++;
|
|
XtSetArg (al[ac], XmNlocationId, "_hometopic"); ac++;
|
|
XtSetValues (onHelpDialog, al, ac);
|
|
/* <emphasis>If the "help on help" dialog is already managed, it might be in another workspace, so unmanage it.</emphasis> */
|
|
if (XtIsManaged (onHelpDialog))
|
|
XtUnmanageChild (onHelpDialog);
|
|
|
|
/* <emphasis>Manage the "help on help" dialog.</emphasis> */
|
|
XtManageChild (onHelpDialog);
|
|
|
|
break;
|
|
|
|
</programlisting>
|
|
<para>To see how the rest of the <function>HelpRequestCB()</function> function
|
|
might be structured, refer to the example in <xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.HReq.mkr.10">.</para>
|
|
</sect3>
|
|
<sect3 id="HRDC.H4Hlp.div.13">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.CrDia.mkr.7"></para>
|
|
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.HReq.mkr.5">
|
|
</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.H4Hlp.div.14">
|
|
<title id="HRDC.H4Hlp.mkr.6">Writing Your Own Help on Help Volume</title>
|
|
<para>If you need to provide your own help on help volume, you should start
|
|
with the existing Help4Help volume and then make the necessary changes. All
|
|
the source files used to write the Help4Help volume are provided in the
|
|
<filename>/usr/dt/dthelp/help4help/C</filename> directory.</para>
|
|
<para>To prevent installation conflicts, name your help on help volume something
|
|
other than Help4Help. Consider picking a name that is specific to your product.
|
|
For example, if your application's help volume is Newapp, your help for help
|
|
volume could be NewappH4H.</para>
|
|
<sect2 id="HRDC.H4Hlp.div.15">
|
|
<title>Required Entry Points</title>
|
|
<para>To ensure that context-sensitive help within a help dialog operates
|
|
correctly, you must provide the following entry points (IDs) within your help
|
|
on help volume. (These are already included in the Help4Help source files.)
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colwidth="158*">
|
|
<colspec align="left" colwidth="370*">
|
|
<tbody>
|
|
<row>
|
|
<entry align="center" valign="top"><para>ID</para></entry>
|
|
<entry align="center" valign="top"><para>Topic Description</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><command>_hometopic</command></para></entry>
|
|
<entry align="left" valign="top"><para>Displays an introduction to using the
|
|
help system. This topic is displayed when you choose Using Help from the general
|
|
help dialog's Help menu, or when you press F1 in a quick help dialog. This
|
|
ID is generated automatically for PartIntro, so do not try to specify it explicitly.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><command>_copyright</command></para></entry>
|
|
<entry align="left" valign="top"><para>Displays the copyright and version
|
|
information for the help on help volume. This topic is displayed when you
|
|
choose Version from the general help dialog's Help menu. This ID is generated
|
|
automatically for LegalNotice, so do not try to specify it explicitly.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><command>history</command></para></entry>
|
|
<entry align="left" valign="top"><para>Displays a topic that describes how
|
|
to use the History dialog. This topic is displayed when you choose Help or
|
|
press F1 within the History dialog.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><command>printing</command></para></entry>
|
|
<entry align="left" valign="top"><para>Displays a topic describing how to
|
|
use the Print dialog. This topic is displayed when you choose Help or press
|
|
F1 within the Print dialog.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><command>index-search</command></para></entry>
|
|
<entry align="left" valign="top"><para>Displays a topic describing how to
|
|
use the Index Search dialog. This topic is displayed when you choose Help
|
|
or press F1 within the Index Search dialog.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><command>volume-select</command></para></entry>
|
|
<entry align="left" valign="top"><para>Displays a topic describing how to
|
|
use the Search Volume Selection Dialog. This topic is displayed when you choose
|
|
Help or press F1 within the Search Volume Selection Dialog.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
<sect2 id="HRDC.H4Hlp.div.16" role="Procedure">
|
|
<title id="HRDC.H4Hlp.mkr.7">To Copy the Help4Help Source Files</title>
|
|
<orderedlist><listitem><para>Copy the entire <filename>/usr/dt/dthelp/help4help/C</filename> directory to a new working directory ( <symbol role="Variable">new-dir</symbol>) using a command like this:</para>
|
|
<para><command>cp -r /usr/dt/dthelp/help4help/C <symbol role="Variable">new-dir</symbol></command></para>
|
|
<para>This creates <symbol role="Variable">new-dir</symbol> and copies all
|
|
the files and directories into it.</para>
|
|
</listitem><listitem><para>To permit editing the files (which are copied as
|
|
read only), change the permissions using a command like this:</para>
|
|
<programlisting>chmod -R u+w <symbol role="Variable">new-dir</symbol></programlisting>
|
|
</listitem></orderedlist>
|
|
<para>The Help4Help volume uses these DocBook source files:</para>
|
|
<itemizedlist><listitem><para><filename>MetaInfo.sgm</filename></para>
|
|
</listitem><listitem><para><filename>Toc.sgm</filename></para>
|
|
</listitem><listitem><para><filename>Tasks.sgm</filename></para>
|
|
</listitem><listitem><para><filename>Home.sgm</filename></para>
|
|
</listitem><listitem><para><filename>Concepts.sgm</filename></para>
|
|
</listitem><listitem><para><filename>Ref.sgm</filename></para>
|
|
</listitem><listitem><para><filename>Appendix.sgm</filename></para>
|
|
</listitem></itemizedlist>
|
|
<para>Graphics are stored in the <filename>graphics</filename> subdirectory.
|
|
</para>
|
|
<para>Be sure to rename the <filename>Help4Help.sgm</filename> file before
|
|
running DocBook. Your help on help volume should have a unique name to prevent
|
|
conflicts with other help on help volumes.</para>
|
|
<sect3 id="HRDC.H4Hlp.div.17">
|
|
<title>Example</title>
|
|
<para>The following commands create a copy of the help on help volume and
|
|
make its files writable. (Presumably the <filename>projects</filename> subdirectory
|
|
already exists.)</para>
|
|
<programlisting>cp -r /usr/dt/dthelp/help4help/C /users/dex/projects/NewHelp4Help
|
|
chmod -R u+w /users/dex/projects/NewHelp4Help</programlisting>
|
|
<para>To build a new version of the run-time help files, first ensure that
|
|
the directory <filename>/usr/dt/bin</filename> is in your search path. Then
|
|
change to the new directory, rename the <filename>Help4Help.sgm</filename>
|
|
file, and run DocBook:</para>
|
|
<programlisting>cd /users/dex/projects/NewHelp4Help
|
|
mv Help4Help.sgm NewH4H.sgm
|
|
dtDocBook NewH4H</programlisting>
|
|
<para>When the DocBook software is done, you can display the new help on help
|
|
volume using this command:</para>
|
|
<para><command>dthelpview -helpVolume NewH4H</command></para><?Pub Caret>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
|