509 lines
29 KiB
Plaintext
509 lines
29 KiB
Plaintext
<!-- $XConsortium: ch04.sgm /main/15 1996/10/22 14:42:40 cdedoc $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<chapter id="HRDC.CrHV.div.1">
|
|
<title id="HRDC.CrHV.mkr.1">Processing and Displaying a Help Volume</title>
|
|
<para>This chapter shows you how to process your marked-up help files to create
|
|
an online format that you view using the Help System. It also describes how
|
|
to make your help volume accessible from the desktop Front Panel Help Viewer.
|
|
</para>
|
|
<informaltable id="HRDC.CrHV.itbl.1" frame="All">
|
|
<tgroup cols="1">
|
|
<colspec colname="1" colwidth="4.0 in">
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Creating Run-Time Help Files89'--><xref
|
|
role="JumpText" linkend="HRDC.CrHV.mkr.2"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Create a Run-Time Help Volume89'--><xref
|
|
role="JumpText" linkend="HRDC.CrHV.mkr.3"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Viewing a Help Volume92'--><xref
|
|
role="JumpText" linkend="HRDC.CrHV.mkr.6"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Display a Help Volume92'--><xref
|
|
role="JumpText" linkend="HRDC.CrHV.mkr.7"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Adding Your Help to the Index Volume94'--><xref
|
|
role="JumpText" linkend="HRDC.CrHV.mkr.8"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Printing Help Topics98'--><xref role="JumpText"
|
|
linkend="HRDC.CrHV.mkr.13"></para></entry>
|
|
</row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Testing Your Help99'--><xref role="JumpText"
|
|
linkend="HRDC.CrHV.mkr.15"></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<sect1 id="HRDC.CrHV.div.2">
|
|
<title>Overview</title>
|
|
<para>Before a help volume can be displayed, you must create a run-time help
|
|
file by processing your files with the DocBook software. Run-time files use
|
|
an online presentation format called <emphasis>Semantic Delivery Language</emphasis> (SDL). An<filename>.sdl</filename> file extension identifies a
|
|
run-time help file.</para>
|
|
<para>The utility <command>dtdocbook</command> takes documents conforming
|
|
to the DocBook 2.2.1 DTD subelement Part and produces documents conforming
|
|
to the SDL 1.2 DTD, which can serve as input to the DtHelp viewer.</para>
|
|
<para>During translation, several items are precomputed to speed run-time
|
|
display of the document. These items include: the table of contents, the keyword
|
|
index, resolution of cross-references, and labeling of ordered lists. The
|
|
SDL conforming document produced by the translation is compressed by default.
|
|
</para>
|
|
<graphic id="HRDC.CrHV.igrph.1" entityref="HRDC.CrHV.fig.1"></graphic>
|
|
<para>The Help System defines desktop actions and data types for help-specific
|
|
files. This lets you easily process and view a run-time help file from the
|
|
desktop.</para>
|
|
<sect2 id="HRDC.CrHV.div.3">
|
|
<title>DocBook Software</title>
|
|
<para>The DocBook software can be invoked automatically by double-clicking
|
|
a help source file in File Manager or by running the <command>dtdocbook</command>
|
|
command manually in a terminal window.</para>
|
|
<para><command>dtdocbook</command> does two significant tasks:</para>
|
|
<orderedlist><listitem><para>The DocBook <emphasis>parser</emphasis> converts
|
|
your marked-up files into an internal format (Semantic Delivery Language)
|
|
understood by the Help System. If you've made any markup errors, the errors
|
|
are reported in a file named <symbol role="Variable">volume</symbol><filename>.log</filename>.</para>
|
|
</listitem><listitem><para>If there are no parser errors, the master help
|
|
volume file (<symbol role="Variable">volume</symbol><filename>.sdl</filename>)
|
|
is created.</para>
|
|
</listitem></orderedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.4">
|
|
<title>Viewing Your Volume</title>
|
|
<para>After processing your source files with DocBook, your help volume is
|
|
ready to be displayed. You can display it by double-clicking the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file icon in File
|
|
Manager, or use the <command>dthelpview</command> command in a terminal window.
|
|
</para>
|
|
<graphic id="HRDC.CrHV.igrph.2" entityref="HRDC.CrHV.fig.2"></graphic>
|
|
<para>If you have written help for an application and the application is ready
|
|
to use, you can display your help by running the application and asking for
|
|
help.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.CrHV.div.5">
|
|
<title id="HRDC.CrHV.mkr.2">Creating Run-Time Help Files</title>
|
|
<para>When you run <command>dtdocbook</command>, it reads your <symbol role="Variable">volume</symbol><filename>.sgm</filename> file and any additional source files
|
|
that are included using entities. It also validates graphics file names.</para>
|
|
<para>Be sure the <command>/usr/dt/bin/dtdocbook</command> command is in your
|
|
search path. (If you're not sure how to do this, ask your system administrator.)
|
|
</para>
|
|
<sect2 id="hrdc.crhv.div.6" role="Procedure">
|
|
<title id="hrdc.crhv.mkr.3">To Create a Run-Time Help Volume</title>
|
|
<orderedlist><listitem><para>Open File Manager and change to the directory
|
|
where your <symbol role="Variable">volume</symbol><filename>.sgm</filename>
|
|
file is located.</para>
|
|
<graphic id="hrdc.crhv.igrph.3" entityref="HRDC.CrHV.fig.3"></graphic>
|
|
</listitem><listitem><para>Select the file icon.</para>
|
|
</listitem><listitem><para>Choose Compile from the File Manager Selected menu.
|
|
</para>
|
|
<para>The <symbol role="Variable">volume</symbol><filename>.sgm</filename>
|
|
file is processed and creates a <symbol role="Variable">volume</symbol><filename>.sdl</filename> file and a <symbol role="Variable">volume</symbol><filename>.log</filename> file.</para>
|
|
</listitem></orderedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.7">
|
|
<title>DocBook Output</title>
|
|
<para>DocBook takes the file <symbol role="Variable">volume</symbol><filename>.sgm</filename> as its input and outputs several files:</para>
|
|
<itemizedlist><listitem><para>Most importantly, the final output file, a
|
|
run-time help volume, named <symbol role="Variable">volume</symbol><filename>.sdl</filename>.</para>
|
|
</listitem><listitem><para>If any errors occurred during processing, they
|
|
are reported in an error file named <symbol role="Variable">volume</symbol><filename>.log</filename>, typically removed after use.</para>
|
|
</listitem></itemizedlist>
|
|
<para>The <symbol role="Variable">volume</symbol><filename>.sdl</filename>
|
|
file is not created until the source file is without errors.</para>
|
|
<para>The <symbol role="Variable">volume</symbol><filename>.sdl</filename>,
|
|
file, plus your graphics files, are read by the Help System to display help
|
|
topics.</para>
|
|
<para>The run-time help file has the same base name as your <symbol role="Variable">volume</symbol><filename>.sgm</filename> file. For example, if your source
|
|
file is named <filename>Librarian.sgm</filename>, then the help volume name
|
|
is <filename>Librarian.sdl</filename>.</para>
|
|
<para>The <command>dtdocbook</command> utility accepts a single file as an
|
|
argument. If the file name ends in the characters “<filename>.sgm</filename>”,
|
|
those characters are assumed to be the file name extension and are removed
|
|
to create the file base names for all intermediate files and for the final
|
|
output file.</para>
|
|
<para>When the <command>dtdocbook -c</command> or the <command>dtdocbook -d</command> option is specified to request compression or decompression of
|
|
an existing SDL file, the input file name will end in the characters “<filename>.sdl</filename>”. Again, those characters are assumed to be the file
|
|
name extension and are removed to create the file base names for all intermediate
|
|
files and for the final output file.</para>
|
|
<para>If the <command>-c</command> option is specified and the file is already
|
|
compressed, the file will be decompressed and recompressed. This action is
|
|
useful as a means to verify the integrity of a compressed SDL file.</para>
|
|
<para>If the <command>-d</command> is specified and the file is already decompressed,
|
|
the file will be re-parsed, all precomputations will be performed, and the
|
|
file will be re-written. This action is useful as a means to verify the integrity
|
|
of an SDL file. It is also useful for forcing a recomputation of the table
|
|
of contents, including byte offsets to individual help topics, when such recomputation
|
|
is made necessary, for example, by editing the SDL file directly.</para>
|
|
<para>The final output file name extension will always be “<filename>.sdl</filename>”, unless the <command>dtdocbook -o</command> option
|
|
is specified, in which case the <symbol role="Variable">filename</symbol>
|
|
argument to <command>dtdocbook -o</command> will be used as given as the output
|
|
file name.</para>
|
|
<caution>
|
|
<para>Never rename a run-time help file or graphics file after running <command>dtdocbook</command>. The information stored in the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file depends on the original names.
|
|
If you rename your <symbol role="Variable">volume</symbol><filename>.sgm</filename>
|
|
file or any of your graphic files, be sure to rerun <command>dtdocbook</command>.
|
|
</para>
|
|
</caution>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.8" role="Procedure">
|
|
<title>To Run the dtdocbook Command Manually</title>
|
|
<itemizedlist><listitem><para>Run the <command>dtdocbook</command> command
|
|
as follows:</para>
|
|
<para><command>dtdocbook</command> <symbol>options</symbol> <symbol>volume</symbol></para>
|
|
<para>Observe that <symbol>options</symbol> are entered before the <symbol>volume</symbol> name. <xref role="SecTitleAndPageNum" linkend="HRDC.CmdS.mkr.2">
|
|
lists all available options.</para>
|
|
</listitem></itemizedlist>
|
|
<sect3 id="HRDC.CrHV.div.9">
|
|
<title>Examples of Command Options.sgm</title>
|
|
<para>The following command processes a help volume named <filename>MyVolume</filename>:</para>
|
|
<programlisting>dtdocbook MyVolume</programlisting>
|
|
<para>Using the <command>-r</command> option removes all files previously
|
|
generated by processing a source file of <filename>MyVolume.sgm</filename>:
|
|
</para>
|
|
<programlisting>dtdocbook -r MyVolume.sgm</programlisting>
|
|
<para>The following command processes the source file named <filename>MyVolume.sgm</filename> and leaves the result in the file named <filename>Other_File.sdl</filename>::</para>
|
|
<programlisting>dtdocbook -o Other_File.sdl MyVolume.sgm</programlisting>
|
|
<para>Using the <command>-v</command> option causes the progress of the processing
|
|
to be displayed on your screen:</para>
|
|
<programlisting>dtdocbook -v MyVolume</programlisting>
|
|
</sect3>
|
|
<sect3 id="HRDC.CrHV.div.11">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><xref role="ChapNumAndTitle"
|
|
linkend="HRDC.Inst.mkr.1"> explains which help files are included in your
|
|
application installation package.</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.12" role="Procedure">
|
|
<title id="HRDC.CrHV.mkr.5">To Review and Correct Parser Errors</title>
|
|
<para>The primary source of error messages will be the SGML parser. Most of
|
|
them will be SGML syntax error messages, and a few will be of the "file not
|
|
found" variety.</para>
|
|
<para>The two passes of the translation process that takes the source file
|
|
from SGML to SDL will also generate syntax error messages and "file not found"
|
|
messages, but to a lesser degree. The second of the two passes will issue
|
|
error messages rarely, since all the syntax and context will have been checked
|
|
by then.</para>
|
|
<para>After running <command>dtdocbook</command>, look at the contents of
|
|
the <symbol role="Variable">volume</symbol><filename>.log</filename> file
|
|
(where <symbol role="Variable">volume</symbol> is the base name of your <symbol role="Variable">volume</symbol><filename>.sgm</filename> file).</para>
|
|
<para>It is quite possible for a single, simple error to produce several error
|
|
messages, because the error may cause the parser to lose track of the intended
|
|
context, making it impossible to interpret subsequent markup properly.</para>
|
|
<sect3 id="HRDC.CrHV.div.13">
|
|
<title>Common Errors</title>
|
|
<para>Most processing errors result from these common mistakes:</para>
|
|
<itemizedlist><listitem><para>Omitting an end tag</para>
|
|
</listitem><listitem><para>Using an incorrect entity name</para>
|
|
</listitem><listitem><para>Referring to an invalid element ID</para>
|
|
</listitem></itemizedlist>
|
|
<para>Omitting an end tag for an element is a common mistake. <emphasis>Virtually
|
|
all DocBook elements require end tags.</emphasis> Check your markup when you
|
|
have nested one structurally complex element within another, such as a figure
|
|
within a list.</para>
|
|
<para>Errors can also be introduced by using an incorrect entity name. In
|
|
most instances, it is simply a misspelled word. In other cases, an entity
|
|
name may have been changed, but cross-references to the original name were
|
|
overlooked. When you change an entity name, remember to search your source
|
|
file (or files) for all instances of the entity name.</para>
|
|
<para>Errors can also be introduced by changing the ID assigned to an element,
|
|
since this affects any cross-reference or link to that topic. When you change
|
|
an ID, remember to search your source file (or files) for all instances of
|
|
that ID.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.CrHV.div.14">
|
|
<title id="HRDC.CrHV.mkr.6">Viewing a Help Volume</title>
|
|
<para>The Help Viewer can be used to display any help volume. It supports
|
|
all DocBook hyperlinks but not application-defined links (because it cannot
|
|
know how your links are to be interpreted).</para>
|
|
<para>If you are writing application help and your application is ready to
|
|
use, you can also view your help by running your application, then requesting
|
|
help just as a user would.</para>
|
|
<sect2 id="HRDC.CrHV.div.15" role="Procedure">
|
|
<title id="HRDC.CrHV.mkr.7">To Display a Help Volume</title>
|
|
<orderedlist><listitem><para>Open File Manager and change to the directory
|
|
where the <symbol role="Variable">volume</symbol><filename>.sdl</filename>
|
|
file is located.</para>
|
|
</listitem><listitem><para>Double-click its icon.</para>
|
|
<para>The default action displays the file using the Help Viewer.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.CrHV.div.16" role="Procedure">
|
|
<title>To Run the dthelpview Command Manually</title>
|
|
<itemizedlist><listitem><para>If the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file for the volume you want to display is either in the current
|
|
directory or has been registered, execute this command:</para>
|
|
<para><command>dthelpview -helpVolume <symbol role="Variable">volume</symbol><filename>.sdl</filename></command></para>
|
|
<para><emphasis>Or,</emphasis> if the <symbol role="Variable">volume</symbol><filename>.sdl</filename> is in another directory (and hasn't been registered), execute
|
|
this command:</para>
|
|
<para><command>dthelpview -helpVolume /<symbol>full-path</symbol>/ <symbol>volume</symbol>.sdl</command></para>
|
|
</listitem></itemizedlist>
|
|
<para>The <command>-helpVolume</command> parameter can be shortened to <command>-h</command> in any of these commands.</para>
|
|
</sect3>
|
|
<sect3 id="HRDC.CrHV.div.17">
|
|
<title>Example</title>
|
|
<para>Suppose you have just edited your help volume. First, process it with
|
|
the DocBook software:</para>
|
|
<programlisting>dtdocbook MyVolume.sgm</programlisting>
|
|
<para>If no errors occurred, you could then display it with this command:
|
|
</para>
|
|
<programlisting>dthelpview -h MyVolume.sdl</programlisting>
|
|
</sect3>
|
|
<sect3 id="HRDC.CrHV.div.18">
|
|
<title>See Also</title>
|
|
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.Inst.mkr.9"></para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
<sect3 id="HRDC.CrHV.div.19">
|
|
<title>Example: A Personal Help Directory</title>
|
|
<para>During a project, you may want to access the help volume you are developing,
|
|
but not expose it to all users on your system. For example, suppose your
|
|
working directory is <filename>/projects/help</filename> and your help volume
|
|
is named <filename>Myvolume</filename>.</para>
|
|
<para>First, create the personal help directory in your home directory where
|
|
you can register the volume:</para>
|
|
<programlisting>mkdir -p $HOME/.dt/help/C</programlisting>
|
|
<para>Now create a symbolic link to the <filename>Myvolume.sdl</filename>
|
|
file (which is created by the DocBook software):</para>
|
|
<programlisting>ln -s /projects/help/Myvolume.sdl $HOME/.dt/help/C/Myvolume.sdl
|
|
</programlisting>
|
|
<para>You can now display the volume with the following command (regardless
|
|
of your current directory) because the<filename>.dt/help/C</filename> directory
|
|
within your home directory is one of the first places the Help System looks
|
|
for help volumes.</para>
|
|
<programlisting>dthelpview -helpVolume Myvolume.sdl</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.CrHV.div.20">
|
|
<title id="HRDC.CrHV.mkr.8">Adding Your Help to the Index Volume</title>
|
|
<para>The desktop provides a special help volume called the index volume that
|
|
lists help volumes available on your system. The index volume is displayed
|
|
by clicking the Help Viewer control in the Front Panel.</para>
|
|
<para>You can view assorted help volumes directly from the index volume. This
|
|
allows access to application-specific help without starting the application.
|
|
If you are writing standalone help, this is the only way for users to get
|
|
to your help.</para>
|
|
<figure>
|
|
<title id="HRDC.CrHV.mkr.9">Index help volume displaying help families</title>
|
|
<graphic id="HRDC.CrHV.grph.1" entityref="HRDC.CrHV.fig.4"></graphic>
|
|
</figure>
|
|
<para>To make your help volume available in the index volume, you create a
|
|
help family file. When your application is registered on the desktop, the
|
|
presence of a family file causes the help volume to be included in the index
|
|
volume.</para>
|
|
<sect2 id="HRDC.CrHV.div.21">
|
|
<title id="HRDC.CrHV.mkr.10">Index Volume</title>
|
|
<para>A desktop utility creates and updates the index volume. When a user
|
|
clicks on the Front Panel Help Viewer for the first time, the utility is automatically
|
|
run. It identifies help volumes and help family files that are located in
|
|
the help search path directories. It creates a file called <filename>index.hv</filename> in the user's <filename>HomeDirectory/.dt/help/$DTUSERSESSION</filename> directory. After its initial creation, the volume is updated only
|
|
if changes have occurred.</para>
|
|
<para>To manually update the index volume, refer to <xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.CmdS.mkr.5">.</para>
|
|
<para>Any help volume listed in the index volume can be viewed by selecting
|
|
the volume title. Because you can display and navigate through different volumes,
|
|
the index help window includes an additional button, called Top Level.You
|
|
can use this button to return to the index list after displaying one or more
|
|
volumes.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.22">
|
|
<title>Help Family File</title>
|
|
<para>The desktop utility examines help family files to identify which help
|
|
volumes are gathered into the index volume. <xref role="CodeOrFigureOrTable"
|
|
linkend="HRDC.CrHV.mkr.9"> on <xref role="PageNum" linkend="HRDC.CrHV.mkr.9">
|
|
shows two help families, Common Desktop Environment and Overview and Basic
|
|
Desktop Skills, listed in the index volume. Each family file consists of
|
|
one or more related help volumes. For example, the Common Desktop Environment
|
|
family includes different volumes that describe the desktop.</para>
|
|
<para>Refer to the Advanced User's and System Administrator's Guide for a
|
|
detailed explanation of how an application and its help files are installed
|
|
on the desktop.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.23" role="Procedure">
|
|
<title id="HRDC.CrHV.mkr.11">To Create a Help Family</title>
|
|
<orderedlist><listitem><para>Pick a file name that is unique to your product.
|
|
Use the<filename>.hf</filename> extension to identify the file as a <emphasis>help family</emphasis>.</para>
|
|
<para><filename><symbol>family</symbol>.hf</filename></para>
|
|
</listitem><listitem><para>Enter the following lines into the file:</para>
|
|
<programlisting>*.charSet: <symbol>character-set</symbol>
|
|
*.title: <symbol>family title</symbol>
|
|
*.bitmap: <symbol>icon file</symbol>
|
|
*.abstract: <symbol>family abstract</symbol>
|
|
*.volumes: <symbol>volume volume volume ...</symbol></programlisting>
|
|
<para>Where <symbol>character-set</symbol> specifies the character set used
|
|
by the <symbol>family title</symbol> and <symbol>family abstract</symbol>
|
|
strings. <xref role="SecTitleAndPageNum" linkend="HRDC.Lang.mkr.11"> for a
|
|
list of supported character sets. The <symbol>family title</symbol> and <symbol>family abstract</symbol> should not contain any DocBook markup; this file
|
|
is <emphasis>not</emphasis> processed with the DocBook software.</para>
|
|
<para>The <symbol>icon file</symbol> is optional. If you provide one, the
|
|
path you use to specify the location of the file should be a complete path
|
|
name. If you do not provide an icon, do not include the <filename>*.bitmap</filename> resource in your family file.</para>
|
|
<para>The list of <symbol>volume</symbol> names identifies which volumes belong
|
|
to the family. The volumes will be listed in the order they appear on this
|
|
line. A volume may be listed in more than one family.</para>
|
|
<para>If any of the values occupy more than one line, end each line —
|
|
except the last — with a backslash (<filename>\</filename>).</para>
|
|
<para>Any line in the file that begins with an <filename>!</filename> (exclamation
|
|
mark) is a comment line and is ignored.</para>
|
|
</listitem><listitem><para>When you prepare your final product, you should
|
|
install your <symbol>family</symbol><filename>.hf</filename> file with the
|
|
rest of your help files. When the desktop integration script, (<command>dtappintegrate</command>) is run, it creates the symbolic links to your family file.</para>
|
|
<para>The <citetitle>Advanced User's and System Administrator's Guide</citetitle>
|
|
describes how to run the <command>dtappintegrate</command> script.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.CrHV.div.24">
|
|
<title>Example</title>
|
|
<para>Here's an example of a family file for the desktop's online help.</para>
|
|
<programlisting>*.charSet: ISO-8859-1
|
|
*.title: Common Desktop Environment
|
|
*.bitmap: /usr/dt/appconfig/help/C/graphics/cdelogo.pm
|
|
*.abstract: Overview and Basic Desktop Skills \
|
|
* File Manager and the Desktop \
|
|
* Front Panel \
|
|
* Application Manager \
|
|
* Style Manager \
|
|
* Text Editor \
|
|
* Mailer
|
|
*.volumes: Intromgr.sdl Filemgr.sdl FPanel.sdl
|
|
Appmanager.sdl Stylemgr.sdl
|
|
Textedit.sdl Mailer.sdl
|
|
|
|
</programlisting>
|
|
<para>The help family file actually included with the desktop software may
|
|
not exactly match this example.</para>
|
|
</sect3>
|
|
<sect3 id="HRDC.CrHV.div.25">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.Lang.mkr.5"> for a list of supported character set names</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="hrdc.crhv.div.26" role="Procedure">
|
|
<title id="hrdc.crhv.mkr.12">To Display the Index Volume</title>
|
|
<orderedlist><listitem><para>Choose the Help Viewer control from the desktop's
|
|
Front Panel.</para>
|
|
<graphic id="hrdc.crhv.igrph.4" entityref="HRDC.CrHV.fig.5"></graphic>
|
|
</listitem><listitem><para>Scroll the help window to view the help families
|
|
available on your system.</para>
|
|
</listitem><listitem><para>If desired, display a volume by selecting the help
|
|
family title.</para>
|
|
</listitem></orderedlist>
|
|
<note>
|
|
<para>To view help information about the Help System, choose the title Common
|
|
Desktop Environment and then Desktop Help System.</para>
|
|
</note>
|
|
<sect3 id="hrdc.crhv.div.27" role="Procedure">
|
|
<title>To Display the Index Volume Manually</title>
|
|
<itemizedlist><listitem><para>Run the <command>dthelpview</command> command
|
|
as follows:</para>
|
|
<programlisting>dthelpview -helpVolume index</programlisting>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
<sect3 id="hrdc.crhv.div.28">
|
|
<title>See Also</title>
|
|
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="hrdc.cmds.mkr.4">
|
|
lists <command>dthelpview</command> command line.</para>
|
|
</listitem><listitem><para><command>dthelpgen</command>(1) man page</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.CrHV.div.29">
|
|
<title id="HRDC.CrHV.mkr.13">Printing Help Topics<indexterm><primary>printing</primary><secondary>help topics</secondary></indexterm></title>
|
|
<para>After displaying your help volume, you can print help topics. Using
|
|
the Print dialog box shown in <!--Original XRef content: 'Figure 4‐2'--><xref
|
|
role="CodeOrFigureOrTable" linkend="HRDC.CrHV.mkr.14"> you can print an individual
|
|
topic, a table of contents and index information, or the entire help volume.
|
|
Printed output omits graphics.</para>
|
|
<figure>
|
|
<title id="HRDC.CrHV.mkr.14">Help print dialog box</title>
|
|
<graphic id="HRDC.CrHV.grph.2" entityref="HRDC.CrHV.fig.6"></graphic>
|
|
</figure>
|
|
</sect1>
|
|
<sect1 id="HRDC.CrHV.div.30">
|
|
<title id="HRDC.CrHV.mkr.15">Testing Your Help</title> <indexterm><primary>testing</primary><secondary>help</secondary></indexterm><indexterm><primary>validating hyperlinks</primary></indexterm><indexterm><primary>hyperlink</primary><secondary>validating hyperlinks</secondary></indexterm><indexterm>
|
|
<primary>verifying application entry points</primary></indexterm><indexterm>
|
|
<primary>application entry points, verifying</primary></indexterm><indexterm>
|
|
<primary>entry points in application, verifying</primary></indexterm><indexterm>
|
|
<primary>points, entry, verifying in application</primary></indexterm><indexterm>
|
|
<primary>testing</primary><secondary>graphics on various displays</secondary>
|
|
</indexterm><indexterm><primary>graphics, testing on various displays</primary>
|
|
</indexterm><indexterm><primary>displays, testing graphics on various</primary>
|
|
</indexterm>
|
|
<para>Testing your help volume is as important as testing any software product.
|
|
Here are some tips to help you plan your testing.</para>
|
|
<sect2 id="HRDC.CrHV.div.31">
|
|
<title>Validating Hyperlinks</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Display your help volume and
|
|
try every hyperlink. Any underlined text (solid or dashed underlines) is a
|
|
hyperlink. Also, test any graphics that are hyperlinks. Graphic hyperlinks
|
|
use an open-cornered border (dashed or solid) around the image as a hyperlink
|
|
cue.</para>
|
|
</listitem><listitem><para>If you are writing application-specific help and
|
|
you have included any <command>JumpNewView</command>, <command>Man</command>,
|
|
or <command>AppDefined</command> links, you must test these links from your
|
|
application. Testing such links using <command>dthelpview</command> does not
|
|
ensure that the links will operate correctly from within your application.
|
|
</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.32">
|
|
<title>Verifying Entry Points</title>
|
|
<para>If you are writing application-specific help that uses IDs to access
|
|
particular help topics, there are two ways to verify that the IDs have been
|
|
properly established within the help volume:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Run your application and request
|
|
help just as a user will, trying each of the entry points. This also verifies
|
|
that the application is using the correct IDs.</para>
|
|
</listitem><listitem><para>If your application is not ready to use (still
|
|
under development), you can test each ID by running <command>dthelpview</command>
|
|
for each ID:</para>
|
|
<programlisting>dthelpview -helpVolume <symbol role="Variable">volume.sdl</symbol> -locationId <symbol role="Variable">id</symbol></programlisting>
|
|
<para>Where <symbol role="Variable">id</symbol> is the location ID that you
|
|
want to test. If <command>dthelpview</command> displays the correct topic,
|
|
then the ID is okay.</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.33">
|
|
<title>Checking Index Entries</title>
|
|
<para>Users search or browse a help volume index to find help topics. Examine
|
|
your index entries carefully to eliminate any vague terms or duplicate entries.
|
|
Also select each index entry to verify that the topic displayed is the most
|
|
appropriate information.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.CrHV.div.34">
|
|
<title>Testing Graphics</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Physically run your application
|
|
on various displays to verify that the graphics are acceptable on color,
|
|
grayscale, and monochrome displays.</para>
|
|
</listitem><listitem><para>You can also simulate other displays by changing
|
|
the number of colors used by the desktop. To do so, open Style Manager, choose
|
|
Number Of Colors, and select a different color option.</para>
|
|
</listitem></itemizedlist>
|
|
<sect3 id="HRDC.CrHV.div.36">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><!--Original XRef content: '“Generating
|
|
a Index Help Volume (dthelpgen)” on page 193'--><xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.CmdS.mkr.5"></para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1><?Pub Caret1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
|