What is a "PI marker" or "programming instruction marker"

[Jeremy H. Griffith]

On Wed, 28 Nov 2012 13:38:57 -0800, Robert Lauriston <robert at lauriston.com> wrote:

>An HTML Help alias file should have an .h extension. .hha does not
>ring a bell. An HTML Help project has .hhc (TOC), .hhk, (index), and
>.hhp (project) files, but not .hha that I know of.

For HTML Help CSH, two additional files are required,
the map file (which is indeed an .h file), and the
alias file (for which MS did not specify an extension;
we adopted .hha as a convention).

In the HHP, they are used this way:

[ALIAS]
#include "MyDoc.hha"

[MAP]
#include "resource.h"

For example, resource.h has lines like this:

#define IDH_Export 1090
#define IDH_CnvDsgnr 1080

And the HHA has:

IDH_CnvDsgnr=02x998989.htm
IDH_Export=02x999005.htm

As you see, the alias file is *not* an .h file;
it is not needed by the developers if they are
calling via the API HTMLHelp() with a command
of HH_HELP_CONTEXT, which takes a numeric 
value to specify the specific destination.
That is why the map file is an .h, so that it
can be included in the source code of the
calling application.  What goes to HTML Help
is just the number.

At the HTML Help end, the number is converted
back to the string after the #define; in fact, 
for that file, you can omit the #define, though
that would increase maintenance since you couldn't
use the same file you sent the developers.  So
AFAIK nobody does that.  ;-)

Now HTML Help needs to determine which file the
string is meant to reference.  That's the job
of the alias file, the one we call .hha (but
which can have any name you please).  It maps
the string from the map file to the filename
within the CHM.

An alternative way of calling CSH for HTML Help
is to use the API HTMLHelp() with a command of 
HH_DISPLAY_TOPIC.  That takes the name of the 
file within the CHM as its value.  In that case,
you do not need either the alias or the map file;
you are telling HTML Help yourself which file
to display.  We use that method in Mif2Go and
DITA2Go themselves.  It does require you to
keep the CSH filenames invariant, not a problem
for our usage, but it could be one in an org
where writers and developers do not work together 
as closely.  Hence the first method, using the
HH_HELP_CONTEXT command, is more common.

For more detail, see the Mif2Go User's Guide,
par. 9.11, "Setting up CSH for HTML Help", or
the DITA2Go UG, par. 18.11 (similar content).

Hope that clears up the requirements for CSH
in HTML Help for you, and anyone else who cares.  ;-)

-- Jeremy H. Griffith, at Omni Systems Inc.
  <jeremy at omsys.com>    http://mif2go.com/