|
How to Create Context-Sensitive Help
Introduction
The process of creating context-sensitive help for applications is
generally the same for everyone, regardless of whether you are using
Doc-To-Help or RoboHelp, or another help authoring tool. While some tools
are arguably easier to use than others, they generally help you create the
help topic, give the help topic a context ID (also known as a context
string), then assign a map number to the topic. Map numbers are the link
between your help file and the application calling your help.
Map numbers can be either generated automatically by your help program, or
by the programmer's development tool. In some cases, the programmer
will give you a list of MAP numbers which you then plug in to your help
file. Other times, you will hand off a list of map number and help topics
to the programmer, and she will associate those numbers with your help file
topics.
RoboHelp and Doc-To-Help both provide online help for creating
context-sensitive help. Most times, procedures are specific to the help
tool. Doc-To-Help, hands down, provides the most comprehensive information
in their file d2hcntxt.hlp. I've included information about creating
context-sensitive help from Robohelp and Doc-To-Help here. For more deatils
specific to the application engine your programmer is working with, see the
file: d2hcntxt.hlp.
A suggestion: before you begin, familiarize yourself with the procedures
for both tools and then try creating a very small help file with a couple of
context-sensitive help topics. Ask your developer to plug in the map
numbers for your one or two topics, then test your help file with the
application to see if your context-sensitive help works.
1.0 Using Doc-to-Help to Create Context Sensitive Help
1.1 In This Help File
Context-sensitive help is a boon to users, and can greatly improve an
application's user- friendliness. These benefits, of course, don't come
without a price. Implementing context-sensitive help requires a lot of
collaboration between the help author and the application developer.
In this Help file we show how to use Doc-To-Help to create
context-sensitive help, with tips for both the help author and the
application programmer. In addition, we give specific code examples that
will make it easier to develop and maintain your context-sensitive help.
The complete online-help file, titled �Context-Sensitive Help with
Doc-To-Help� describes in detail how to create context-sensitive help
for the following applications:
Visual Basic 4.0 (32-bit) Access for Windows 95 Power Builder Desktop 4.0
Visual C++ 4.0
2.0 What is Context Sensitive Help?
2.1 Overview
Integrating help into an application used to be easy. The help author
wrote help topics about an application, and when a user needed to access
help, she went to the help menu, brought up the contents screen and
navigated through the Help file until she found what she wanted.
For garden-variety applications, this model of help authoring works well.
Many users and programmers, however, prefer and demand a higher level of
online help. Help files, like the programs they document, have grown
larger over the years. It is no longer convenient for a user to navigate
through an entire Help file to find the section she needs. In a larger
application, she may well never find it.
Enter context-sensitive help. As its name implies, context-sensitive help
offers the user help within the context of what the user was doing at the
time.
2.1.1 The Help Button
At its most basic level, context-sensitive help can be a help button on a
dialog box. To view the help topic for the entire dialog, the user can
simply click on the help button. There's no longer any need to search
through an entire Help file. The jump to the correct topic is automatic
and painless.
This method works well in most situations, but it has one drawback.
Suppose the dialog box has a large number of text boxes, drop-down list
boxes, command buttons, etc. The help for that screen can rapidly exceed
the space provided for by one help screen (and help topics that fill more
than one help screen are harder to read).
2.1.2 What's This Help
A more finely tuned approach to context-sensitive help allows the user to
access popup help topics for individual text boxes, drop-down list boxes,
command buttons, etc. This sort of help is known as What's This help in
Windows 95.
There are three ways to access What's This help in Windows 95. The user
can click on the What's This button in the title bar. The cursor becomes a
special context-sensitive help cursor: an arrow with a question mark
attached to it.
When you click on an item in the dialog box, Windows 95 displays a popup
help topic for that item.
Alternately, the user can press F1 to see popup help for the currently
selected item in the window. Or the user can right-click on the window
item and click on the What's This menu item in the popup menu that appears.
3.0 Creating Context Sensitive Help
3.1 Help Topics
Creating context-sensitive help involves hooking up help topics to specific
items in an application through a mechanism known as map numbers.
3.1.1 Topic IDs and Map Numbers
When Doc-To-Help converts your manual into online help it assigns a topic
ID to each help topic. Then it assigns a numeric identifier known as a
map number to each topic ID. These map numbers can be edited through
Doc-To-Help's Context Map Editor. The topic IDs, along with their
associated map numbers, are then stored in the HPJ file. Map numbers act as
the handle through which an application calls the topics in a Help file.
When an application needs to call context-sensitive help, it passes a map
number to the Help file. The application must have correct map numbers
available to it, because otherwise it cannot call the correct help topic
for context-sensitive help.
3.2 Using Doc-to-Help
3.2.1 The Context Map Editor
Map numbers are essential to creating robust context-sensitive help. Help
authors and program developers both need to reference the same set of map
numbers in order to hook up the application to its Help file properly.
Doc-To-Help's Context Map Editor allows developers and help authors to
create, maintain and share information about map numbers stored in the HPJ
file.
To view the Context Map Editor, first convert your manual into an RTF file
by choosing Make Into Help from the Format menu. When asked if you want to
compile your file into help, say yes. Doc-To-Help will format your manual
into the proper Help format, convert it into an RTF file and produce the
HPJ file when it compiles the RTF file into help. When this is done, choose
Context Map Editor from the Tools Menu. The Context Map Editor will
appear.
The Context Map Editor presents information about map numbers in a tabular
format:
The Topic Title column identifies the help topic by its heading. The topic
ID corresponding to that help topic is shown in the Topic ID column. And
the map number that corresponds to that topic ID is shown in the Map Number
column.
In some circumstances the help author may need to edit the map numbers by
hand. When this is necessary, simply edit the help topic's map number in
the table. Save the map file. Then double-click on the Remap Context
Strings button at the top of the map document. The new map numbers will be
updated in the HPJ file.
The Context Map Editor accepts both decimal and hexadecimal numbers. When
you enter a hexadecimal number, be sure to put 0x before the number itself
so that the help compiler knows that the number is hexadecimal.
3.2.2 Many Map Numbers, One Topic ID
There are several instances when the help author may need to attach many
map numbers to one topic ID. For example, suppose an application developed
in Visual C++ with MFC needs a What's This help topic entitled Resizing the
Window, to describe how to drag a window's resizing handles to change the
window's size.
In a perfect world, the application would generate only one map number for
the outer rim of a window. In C++/MFC, however, each side and corner of a
window generates a different map number. Each one of these map numbers
needs to be mapped to the same help topic, in this case the topic titled
Resizing the Window.
Doc-To-Help's Context Map Editor makes it easy to connect several map
numbers to the same help topic.
3.2.3 Redefining Map Numbers with the Context Map Editor
If you need to define several map numbers for the same topic ID, open up
the Context Map Editor from the RTF file. See The Context Map Editor for
instructions on how to do this. The Context Map document contains
instructions on how to enter map numbers for topics not mapped by
Doc-To-Help. Though this is not technically the same as assigning several
map numbers to the same topic, the procedure is the same.
First, place your cursor below the table created by the Context Map Editor.
Create a line space between the cursor and the preceding table by pressing
the Enter key. Then select AutoText... from the Edit menu. Select the
AutoText entry entitled CustomMapEntries and click on Insert. A one-column
table will appear entitled Entries Not Written by Doc- To-Help.
Entries not written by Doc-To-Help In order to define additional map
numbers for a help topic, simply type the topic ID and then the map number
separated by a tab space. In order to produce a tabbed space in a table,
press CTRL+Tab.
Entries not written by Doc-To-Help
ResizingTheWindow 501
ResizingTheWindow 502
ResizingTheWindow 503
Once all the necessary map numbers have been defined, double-click on the
Remap Context Strings button to write your additions to the Help file. In
the table shown above, the map numbers 501, 502 and 503 can all be used to
access the same help topic, Resizing The Window.
3.2.4 Where Do Map Numbers Come From?
The question is not trivial. Much of the work of creating
context-sensitive help involves using map numbers to match help topics to
relevant parts of an application. When Doc- To-Help creates a Help file,
it creates a default map number for each help topic. In many cases a help
author can simply hand the list of map numbers from the Context Map Editor
to the application developer. The developer will then add the map numbers
to the appropriate parts of the application.
Many rapid application development tools, such as Visual Basic, allow you
to code context-sensitive help in this way. In other cases, map numbers
originate with the application, and it is the help author who must add the
correct map numbers to the Help file. This is true for the development
environments in many lower-level languages, such as Visual C++.
The relative difficulty of implementing context-sensitive help, therefore,
depends almost entirely on the development tool being used.
Consult the Online Help for Doc-to-Help V2.0: Context-Sensitive Help for
Doc-To-Help for an in-depth discussion of creating context-sensitive help
for the following application engines:
Visual Basic 4.0 (32-bit)
Access for Windows 95
Power Builder Desktop 4.0
Visual C++ 4.0
4.0 Creating Context Senstive Help With RoboHelp
Context-sensitive topics are basically no different from any others. They
begin and end with a page break and have one or more special footnotes that
allow them to be used by the Help Compiler. There are, however, two unique
aspects of context-sensitive Help:
Since the user does not need to search for these topics in the Index,
they should not have search keywords (K footnotes). Since the user does
not browse through these topics, they should be part of the Browse Sequence
(+ footnotes).
Tip
Of course, when you use the Create Popup button, RoboHELP automatically
deletes the K and + footnotes.
4.1 Types of context-sensitive Help
Using RoboHELP, you can display context-sensitive Help topics in two ways:
in traditional popup windows or in the new What's This? popup windows. The
only difference between the two is that the new What's This? windows do not
display a title; they are simple definitions.
4.2 Creating a What's This Context Sensitive Help Topic
4.2.1 From RoboHelp 95 Help
This type of Help topic is designed specifically for the Windows 95
conventions regarding What's This? context-sensitive Help. These
definition-style topics are designed to be accessed by a right mouse click
within a dialog box. You must work with the programmer to implement this
type of Help. For more information, see About Context-sensitive Help.
1. Open a Help document.
2. Click Create Popup in the RoboHELP tool palette.
3. Select the New What's This? tab.
4. If you are providing a map file(s) to a programmer:
Enter a Topic ID for the What's This? topic. The default begins with IDH_
as all context-sensitive Help topics should. If you are automatically
generating a map file for this document, this Topic ID will be included. If
you are not automatically generating a map file for this document, jot down
this Topic ID so that you can provide it to the programmer.
If a programmer has given you the map file(s):
Click Choose.
The Choose Topic ID Provided by Development Team dialog box appears.
Click Browse to select a map file.
Select the correct Topic ID.
Click OK.
5. Enter the definition text for the Help topic in the space provided.
6. Click OK.
Note
What's This? style topics do not have a # character contained in their
footnotes. Instead, these topics contain only the $ character.
4.3 Activating MAP File Generation in RoboHelp
Before RoboHELP generates a map file for a particular Help document, it
checks two places: RoboHELP checks the project-wide setting for automatic
map file generation, then checks the individual document setting for
automatic map file generation. If both settings are turned on, RoboHELP
creates a map file for this document. If either setting is turned off,
RoboHELP does not create or maintain a map file for this document.
1. Open a Help document.
2. Click Document Properties from the File menu.
3. Click More.
4. Check Automatic Map File.
5. Enter a starting number if desired.
6. Click OK.
4.4 Using SmartHelp in RoboHelp
Welcome to the SmartHelp OLE Control. This control allows you to quickly
and easily add context-sensitive Help to any of the applications that you
develop by simply placing a button on any form. You can use the SmartHelp
OLE Control to link to any topic in any Windows HLP file. Clicking on the
button at run time displays the selected topic in WinHelp.
Key Features of the SmartHelp OLE Control
Allows you to easily add Help buttons to forms created with Visual Basic,
Visual C++, Visual FoxPro and Access. No need to have the source to the
Help file. SmartHelp reads the Topic IDs from any Windows HLP file.
Allows you to add custom text or graphics to the Help button. Supports
OLE 2.0.
Software Requirements
Any visual or object oriented development tool which supports OLE 2.0,
including the following:
Visual Basic 4.0
Visual C++ 4.0
Visual FoxPro 3.0
Microsoft Access 7.0
4.5 Creating A Context-Sensitive Topic To Display In A Traditional Popup
Window
Topics created in this manner are created without search keywords for the
Index or Browse Strings. This is because users do not need to search for
context-sensitive topics.
1. Open a Help document.
2. Position the cursor where you want to create the context-sensitive popup.
3. Click Create Popup in the RoboHELP tool palette.
4. Select the New Popup tab.
5. Enter the title and body text as you want it to appear.
6. Click OK.
Note
The Topic ID for each context-sensitive topic should begin with the prefix
IDH_. The Windows 95 Help Compiler checks that topics with the IDH_ prefix
are mapped and displays an error message if they are not.
Tip
If possible, place all context-sensitive Help topics in one document. This
means that you can use the automatic map file generation for the entire
Help document. This saves time in creating or assigning specific map
numbers for all context-sensitive topics within various Help documents.
4.6 How to Include a MAP File From a Programmer
1. Open the Help project document.
2. Click Setup Project from the RoboHELP tool palette.
3. Select the Advanced tab.
4. Double-click [Map] Include Files under Setup Sections.
5. Select one or more map files; click Add.
6. Click OK.
|
| +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
How to Run Winhelp 4.0 Files on Windows 3.1
Jack Downing
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
This procedure is useful for those creating help for Windows
3.1, Windows 95, and Windows NT 3.5.1. You can create one help file
with Winhelp 4.0, and distribute the help file along with Win32s
software to your Windows 3.0, 3.1, or 3.11 WFW users.
Winhelp 4.0 supports everything on Windows 3.1 except
context-sensitive help, and, I suspect, multimedia files.
Note:
Once you install Win32s on a Windows 3.1 platform, ANY existing
3.1 help file can run under WINHLP32.EXE and take advantage of
32-bit features such as full text search, user-sizable fonts,
help on top, etc. This is quite a boon!
Installation Procedure
----------------------
1. Copy the following file: DEMON::DEMON35:[SHELF2.WN95HELP]PW1118.EXE
To a C:\TEMP directory on your PC. This is the Win32s package
distributed free by Microsoft.
2. Double-click on PW1118.EXE and it will self-extract in the temp directory.
3. Double-click on the decompressed file: C:\TEMP\SETUP.EXE
4. Setup will install Win32s on your PC. The installation procedure
will create a directory called C:\WN32APP, then ask you if
you want to install FREECELL.EXE. Say YES. The program will
then reboot Windows.
5. Test 32-bit support by running C:\WN32APP\FREECELL.EXE - If this
game works, then you can now run 32-bit applications.
5. In File Manager, Click on File ==> Associate, and associate the
extension HLP with C:\WINDOWS\SYSTEM\WINHLP32.EXE
6. Copy a Winhelp 4.0 file set over to your Windows 3.1 PC. You'll
need: filename.HLP
filename.CNT (contents file, if you have one)
7. Click on the filename.hlp from file manager.
--------------------------------------------------------------------
When you distribute your help file to users...
When packaging your kit for users, include an automatic install kit
that will unpack PW1118.EXE, install Win32S, set up a program group
and an icon for help. The helpicon properties need to be associated
with WINHLP32.EXE
|
| The Following is a Job Aid for using Doc-To-Help
Basics for Writing A Doc-To-Help
Document
Part Number: Doc-to-Help-Aid
February, 1996
Revision/Update Information:
Operating System and Version:
Software Version:
Digital Equipment Corporation
Maynard, Massachusetts
February, 1996
Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.
� Digital Equipment Corporation 1994 (PUT YOUR COPYRIGHT DATE HERE). All rights reserved.
The postpaid Reader's Comments form at the end of this document requests your critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation: [PLACE DIGITAL TRADEMARKS HERE] and the DIGITAL logo.
The following are third-party trademarks:
[PLACE THIRD-PARTY TRADEMARKS HERE]
Microsoft and MS-DOS are registered trademarks and Windows is a trademark of Microsoft Corporation.
All other trademarks and registered trademarks are the property of their respective holders.
[INTERNAL BOOK ID]
Table of Contents
1 Using Doc-To-Help
Procedure
Setting Up The Environment
Creating a Multi file document
Headers and Footers
Index Entries
Glossary
Hot Spots (Hypertext Linking)
Creating a Help File (.hlp)
Preface
Audience
This document is for writers who want to write a document using Doc-to-Help.
For More Information
For more information, refer to the following:
For Microsoft Word for Windows Doc-To-Help
The Microsoft Word online Help
The Word for Windows Notes conference (BOOKIE::WINWORD)
The NSCC Notes conference (TNPUBS::NSCC)
D2H_EDMS Templates User's Guide
Using Doc-To-Help
This chapter covers all basic needs for writing a Doc-To-Help document.
Procedure
This procedure for using Doc-To-Help covers areas form setting up
and environment through accessing and reading .hlp files
Setting Up The Environment
1. Create a new directory for Doc-To-Help, such as D2H.Dir.
2. Load the 4 Doc-To-Help floppy disks into D2H.Dir.
Create a working sub directory under D2h.Dir. Do this for each project
so that working each project and locating files is made easy.
3. Copy D2H_Norm.Dot and D2H_IN.Dot into the template directory.
4. Copy any Blank.Doc file into your working directory. This file contains
hidden code that is needed to process your Doc-To-Help document.
Creating a Multi file document
1. You must be in the Doc-To-Help directory or a Doc-To-Help subdirectory
once you open MS-Word.
2. In the Doc-To-Help window double click on MS-Word.
3. From the file menu select New and then select D2H_Norm.Doc template.
4. In the Set Project window that appears, select Multiple.
5. In the Set Project window change the SuperTitle and Title to your
title, then click on OK.
6. Save Document window appears, click on OK.
7. Doc-To-Help now asks for you to enter the file name for this main
chapter. The Main or Base document contains the cover page, copyright
page, and table of contents. This file is similar to the profile in
VAX Document.
8. Doc-To-Help asks you to name the next chapter which is usually the
Preface.
9. To create other new chapters select from the Insert menu, New Chapter.
10. Put the cursor at the end of chapter title and press enter twice.
On the first enter D2H supplies a header 2 and on the second enter
you are now at a Normal style. You may enter a file at this point or
begin typing.
11. To change the chapter number from 1, do the following:
o From the Tools/Options menu select View, then select Field Codes.
o You will now see the Field Codes in the chapter head which contains
some of the following: ...{Seq Chapter\ r1}.
o Change the 1 to the desired chapter number.
o Follow the steps in this mini procedure to unselect Field Codes.
o Press F9 to update change
o Once chapter is complete close and save.
12. To create an appendix repeat Step 9 and then do the following:
o From the Tools/Options menu select View, then select Field Codes.
o You will now see the Field Codes in the chapter head. From the Tools
menu select Macro. Select the EDMSFormatNewAppendix macro, then Run.
o You will now see the Field Codes in the appendix head which contains
some of the following: ...{Seq Appendix\ r1}.
o Change the 1 to the desired appendix number. Numbers are directly
proportional to letters, or in other words 1=A, 2=B, 3=C, and so on.
o Follow the steps in this mini procedure to unselect Field Codes.
o Press F9 to update change.
o Once the appendix is complete close and save.
Headers and Footers
Page numbers are automatically numbered from your main or base document and
refelect the header and footer titles also from that file. To be on the safe
side check your header and footer as you would in MS-Word.
Index Entries
Index entries in Doc-To-Help are the same as MS-Word. Select the word that
you want to mark as an index entry, and then from the Insert menu select Index
and Tables, then Index, and then Mark Entry.
Glossary
Select a term that you want to add to the Glossary. From the Insert menu
select Glossary Term. From the Glossary Term window input the definition.
Hot Spots (Hypertext Linking)
To create Hot Spots for the entire document do the following:
1. From the Main document select the Insert menu and then Hypertext Link.
2. A window appears and asks if you want to update the Heading List.
Select Yes.
3. A Hypertext process will now run. When complete the Insert Hypertext
window appears.
4. To view the contents of hot spots in subsequent sessions do step 1.
5. To see subset of links double click on the +.
Creating a Help File (.hlp)
1. To create a Help File, from the main file select the Format menu and
then select Make Into Help. The process will take some time to
convert the files.
2. When the process is complete you will get a Doc-To-Help window with
your document table of contents. You may view it at this point.
3. To view at subsequent session open your Main .RTF file.
4. From the Tools menu select Run Help. This procedure will bring up
the Doc-To-Help window to view help files. You may also execute the Doc-To-Help window for viewing by double clicking on Winhelp.exe from the main menu.
iv
v
iii
v
1�2
1�3
1�1
|