HP 3000 Manuals HP 3000 Manuals
Tailoring the Help Text
A help page consists of HP Desk help directives and help text. The
directives used in the construction of help pages must be proceeded by a
dollar sign ($) character. The actions then dictated by the directives
found in a help page are carried out when the help page is installed.
Help page directives (which will be looked at in more detail later in
"Help Directives" ) fall into three categories:
* Installation directives.
* Display control directives.
* Formatting directives.
Before a help page can be accessed by users it must first be INSTALLed.
Identifying Installed Help Pages
You can list all the help pages currently installed on your system using
the SYSTEMLIST command. This command lists each installed help page,
giving its identifier, description, and the capability groups for whom it
is installed. To list help pages you must be the System Administrator or
a user with help installation capability. The use of the SYSTEMLIST
command is described in HP DeskManager Administration.
Alternatively, you can browse through the help pages via the menus, until
you reach the page you require. The page's numeric identifier is
displayed in the top right-hand corner of the screen, although you cannot
access the page using the identifier.
Editing or Creating Help Pages
To edit or create help pages you can use any text editor that produces
USASCII files of un-numbered, 80-byte records. Examples of such
Hewlett-Packard editors are EDIT/3000 and TDP/3000.
The files used to store un-installed help pages can have any name you
choose, though obviously, adopting a naming convention simplifies their
identification.
To edit an existing, installed help page you can use the COPY command to
copy a specific page into the Work Area, as follows:
Workarea> COPY FROM HELP
HP Desk will ask you to identify the page you wish to copy. You can then
edit the file in your Work Area, using any suitable available text
editor.
(If you copy to the Work Area an installed page that has one or more
extension page(s) associated with it, all pages are displayed for editing
as if they were one page. The help system inserts the directive $INSTAG
to indicate where the pages are actually separated. Once edited, only
the page that was copied out has to be re-installed. After editing, the
page can be re-INSTALLed.)
Help Page Layout
A file holding a help page comprises records containing directives and
records containing text. A help directive must start in the first
character position of the record. Any records not starting in this way
are text records.
Text must not be more than 76 characters wide, and for good readability
the maximum width should be less--about 60 characters. Text for a page
can be continuous, or broken into convenient, displayable screen lengths.
The screen can display 19 lines of help text before asking the user to
Press <Return> to continue . You can specify screen breaks in your page
using the $PAGE directive. For clarity, 17 lines is a useful maximum to
display at a time. Up to 15 menu options can be displayed on the screen
at one time.
You can include non-displayed comments in the file, if you want to
document the file, using the $COMMENT directive.
By default help text is displayed left-justified. You can format the
display of help text to be left, right, or center justified, using the
$LJUST, $RJUST, or $CENTER directives. Alternatively, character or line
space can be used to control the format.
Tailoring Menu Pages
You can add one or more options to the end of an existing menu, by
creating an extension page for the menu. This should contain a $IDNONHP
directive, and a $SONS directive pointing to each new menu option. Don't
forget to create sub-menus or text pages for these menu options to
reference.
You can insert an option into an existing menu, if the order of options
in a menu is important. To do this you must edit that menu page, either
to add additional page identifiers into the $SONS directive, or to add a
$TAG directive pointing to a new page of menu items that will be pulled
in.
You can also edit existing menu pages to delete options from appearing in
the menu or to limit the display of some options to certain capability
groups, if you wish.
Tailoring Text Pages
You can add text to the end of an existing text page, by creating an
extension page to the text page. This should contain a $IDNONHP
directive, a $TITLE directive, and the text you want to add. The text
can contain other directives as appropriate.
You can insert text into an existing text page by: editing that page to
include the text at the point desired, editing that page to include a
$TAG directive referencing a new text page that will be pulled in, or by
creating extension page with lower identifier than any existing extension
pages.
You can also delete text from an existing page, or restrict its display
by adding directives, if you wish.
Adding New Help Topics
You can install a keyword (see "Installing Help Keywords" ) that calls
up a specific help page when a user types:
HELP keyword
This works in the same way as a user who wants help on an HP Desk
command, typing
HELP command
This feature can be used as a means of providing direct (rather than
menu) access to existing help pages, or for providing users with help for
a script file or an application that you've installed. But the keyword
can be anything - so you could write help pages on any topic a user might
ask for, from available printers to company organization. Keywords
should be obvious and easy for users to remember.
Keywords are also important if you want to add pages that are not part of
the help hierarchy. Help pages can be added that are not referenced as
sons by any other help page, so the only way that a user can access them
is by keyword access. (However, help pages that are referenced by Script
files or from another application need not be accessible to any HP Desk
users at all.)
Protecting Tailored Pages Against Upgrade
You will want to maintain and protect any customization of your help
system through future versions of HP Desk and its options. To make this
possible a directive called $IDNONHP is provided for you to identify the
files that you write or amend. Any help page identified by this
directive will never be amended when you install an upgraded version of
the help system. In this case, you can print the unapplied upgrades and
make individual decisions on whether to replace each of your tailored
pages with the corresponding new Hewlett-Packard standard page. To
minimize this task you should not change existing help pages for trivial
reasons - you'll only be adding to your workload should Hewlett-Packard
upgrade the help system.
To protect your customization of existing pages you can replace the $ID
directive with this directive. You should always use the $IDNONHP
directive to identify help pages you write yourself.
Writing Good Help Text
When writing help text, you should aim to be:
Accurate Users rely on the information given. When asking
for Help, a user is often already lost.
Concise Help has to convey a lot of information in a small
space.
Direct Short, active sentences are best. Use imperatives
(and don't bother to say please!)
Simple Use everyday language with as few special terms as
possible. If you have to use terms, make sure you
explain them and use them consistently.
When choosing topics to write help text about, remember that to provide
useful, usable, understandable information, you must be able to:
* Separate any explanatory information that's necessary from
instructions.
* Make sure instructions on what to do next are clear, and include
examples.
* If a choice is available, explain each option in turn.
* Refer to manuals for more detailed information, if appropriate,
but remember that these may be updated by Hewlett-Packard from
time to time.
* Use plenty of space to make pages easily readable, and keep pages
as short as possible to avoid information scrolling off screen.
* If pages are to be localized for a foreign territory or translated
into another language, leave extra space to allow for this.
Testing the Usability of your Help Text
Before installing any help text of your own for all intended capability
groups, you should test that your Help:
* Can be accessed in the way(s) intended.
* Provides the information you intended, at the point intended.
* Can be understood by people other than yourself.
Install the help just for yourself, or for a small group of users, and
get these users to try the new pages out. Collect feedback, make any
necessary changes, and then install the help page(s) for all intended
groups.
Installing and Removing Help Files
A Help file has to be installed on the system as a help page before it
can be accessed by HP Desk users. Help files can be installed for access
by users via the help menu system, or via a supplied keyword, using the
INSTALL command. Of course, help pages can be deleted too, using the
REMOVE command.
To install or remove a Help file you must be the system administrator or
a user with help installation capability. The use of both commands is
described in HP DeskManager Administration.
A new help page is created in text format, either in an MPE file or in
the Work Area. An HP Desk user with help installation capability can
then use the INSTALL command to install this new page into the HP Desk
subsystem. Keywords can also be INSTALLed for the help pages (by users
with help installation capabilities).
A help page consists of control commands and the help text itself.
Control commands are denoted by a "$". Lines beginning with a "$" are
compiled when the help page is installed:
For example, if you create a help page as a text item called "Script
Help" in your Work Area, and you give it an identifying number of 9999 in
the text file, then the way to install the page into the help system is:
Workarea > INSTALL HELP
COPY HELP FROM > "Script Help" of workarea
Processing the help text
Enter the names of the groups that can see this page (// to end):
Group: Everyone
Group: //
Help page 9999 installed.
If a help page numbered 9999 already exists, then it will be overwritten
with the new one.
Installing Help Keywords
Once a new help page has been installed it is often best to immediately
install a keyword to reference the page. This is easily done:
Workarea > INSTALL KEYWORD
Enter the Help keyword > SCRIPT
Which page is it to reference > 9012
Enter the group names who may obtain help via this keyword:
(Type // to terminate this list)
Group: Everyone
Group: //
Keyword installed