Re: Map files in ForeHelp ?

[Thom Randolph <thom -at- HALCYON -dot- COM>]

Juley:

I'll explain the ways I've done this....

At 08:01 AM 1/27/99 -0600, you wrote:

>1.  Who generally creates the map files?  I read that it depends on the
>environment the programming was done in.  The first application I'm going to
>write help for was created in Delphi.

The first thing you should do is work with the programmer(s) to
set a symbol naming convention. That way, the symbol names they
use in for help will be consistent with their other constants. For
example, sometimes they want all constants in uppercase, and since
the help file context IDs will be integers, they may want to
prefix the symbol with a lower case "i". So, you might have
topic symbol names such as iTABLEOFCONTENTS, iFILEMENU and
iEDITMENU. You'll want to be sure to choose capitalization and
punctuation standards as well; purely for consistency.

The one thing that both of you must understand is that the
symbol names are inviolate. Once you decide on a symbol name,
it must not change. Well, unless you both agree on the change!

From there, you have two ways to go. In each method, one person
has control and freedom, and the other has to be careful. There
are, of course, a multitude of other, "less correct" ways of
doing this, but these are the two that work reliably.

In the first method, the programmer is God. As they create the
program, they will assign symbols and numbers to the context
IDs of their program UI elements. They should then provide you
with a pascal file containing the constant symbols and the
integer values assigned to them: the Context Mapping file.

For example:

CONST   iTABLEOFCONTENTS = 1000;
        iFILEMENU = 1001;
        iEDITMENU = 1002;
        iNAMEFIELD = 1003;

In Forehelp, you would then create your help topics, setting
the context string of each topic to the appropriate symbol name.
In this scenario, you are the one that must be extremely
careful to get the context strings right.

When the programmer gives you an updated Context Mapping file, you
simply use the Project...Import Context Map command in ForeHelp
to update the context ID values. If the project is large, there
may be multiple mapping files, which ForeHelp handles without
problems.

In the second method, you are God, and the programmer must be
careful. This is often the preferred method, since the Delphi
compiler (and others do too) makes a check between the Context
Mapping file constants and the symbol names the programmer uses.
Also, as the writer, you have a better overall view of the
documentation and help file, and may be generating topics that
they don't use in the UI. If they create the Context Mapping file,
then you'd have all these topics that existed outside that
topic accounting mechanism.

In this scenario, you go merrily along creating help topics to
match the UI, and give each new topic an appropriate context
string. Forehelp makes it easy to create context ID's; just click
the up-arrow in the topic properties dialog box, and it will
automatically choose the next available context ID. But, in
essence, neither you nor the programmer needs to care what the
numbers are (as long as there are no duplications, and you're
both using a current context mapping). Using the symbol names
as the context strings ensures that the numbers match, regardless
of their values (within limits, of course).

Periodically, when either of you wants to test the product
and the help system, have ForeHelp generate an updated Context
Mapping file when it builds the help project. You give the
updated Context Mapping file(s) to the programmer, who simply
includes them in the latest product build. As long as you're
using the same symbol names, all the context matching will
be correct.

Which method you choose depends on how your relationships with
the programmers are structured. If you get early input into the
project, then offer the second method as a way to save them
time and frustration. It's just one more thing they won't have
to worry about. If you come into the project late, the context
ID numbers may already be assigned, and you'll have a harder
time of it.

>2.   Does ForeHelp create map files automatically?

Yes, ForeHelp can create AND import C, C++, Pascal and Visual
Basic Context Mapping files. You can assign a topic to
precisely one Context Mapping file, so I lean toward using
a single file that all parts of the project reference. Delphi
and other compilers are good about not wasting space on unused
constants.

>3.  If I tell a group of programmers that the help is linked to the
application
>by map files will  they know what I'm talking about do I need to know more?

They may or may not, depending on whether they've ever done
GUI programming with the Windows Help system. What's more
important, however, is that they understand the need to use
symbols and keep them in a separate mapping file. Some more
"junior" programmers might just start putting in numerical
values at design time. That will ultimately lead to their
own demise. Context strings and IDs should be managed and
doled out like precious rations. Otherwise, you'll end up
with crossed topics or IDs, and debugging that is tedious
and generally not fun.

For something as intricate as Windows Help files, ForeHelp makes
life much easier. Don't believe me? Create your project using
ForeHelp and then take a look at the various project files that
it creates, and the feeds to the Windows help compilers. You
try and figure those out!

Do you need to know more? Maybe. The Windows API for making
calls to the help system is one of the smaller and easier
to understand, so fear not!

Well, that's all your questions. I hope I've helped more
than confused. And no, I don't work for ForeFront, inc.;
I am just a satisfied customer for several years.

Regards,

Thom Randolph
thom -at- halcyon -dot- com


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=