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

[Jeremy H. Griffith]

On Wed, 28 Nov 2012 08:42:12 -0700, "David Artman" 
<david at davidartman.com> wrote:

>Hi, all--FM8p277 on Win7. This is a long post, but I want to be thorough
>and to show that I've done my due diligence to solve this by myself.

Thank you for that!

>Trying to use DITA2Go (D2G) to produce Compiled HTML Help (CHM) with
>context-sensitivity.
> 
>According to D2G Help, I must "Place a 'TopicAlias' PI marker in the
>text of [my] document where [I] want to display context-sensitive help."
>[D2G Help 18.11.1]

Yes.  The marker syntax is shown in par. 38.1.1, 
"Understanding DITA2Go PI marker syntax", which
is part of the full chapter on PIs, Chapter 38.
PIs are XML Processing Instructions, which we 
call "markers" because they serve the same 
purpose in XML as markers do in Frame.  There
is no DITA element for CSH.

>OK, new marker type named "TopicAlias": no problem.
>Contents of a marker of that type "IDH_about": no problem.
>(I inspect the XML in an editor, and the '<?FM MARKER [TopicAlias]
>IDH_about?>' is within the TITLE tag. 

So there's the problem; the PI syntax you have
from an r/w rule is:

<?FM MARKER [TopicAlias] IDH_about?>

And what we expected, the normal XML form, is:

<?dthtm TopicAlias="IDH_About" ?>

The ones you have would be ignored, since we
don't recognize the target "FM", and use a
different syntax in the body of it.  An example
of our usage is in the D2G User's Guide, in
par. 16.10.2, "Specifying  CSH mappings", 
in the first step.

I don't know how easy it would be to have
FM generate those, in addition to the ones
it makes now (needed for round-tripping the 
XML back into Frame).  We hadn't actually 
seen the PI syntax Frmae used until now.  

We could add support for it to DITA2Go 
fairly easily, if  that syntax is used 
consistently.  What does it do when you 
have more than one item in one marker?

>I'd *kind of* prefer it to be
>before the tag... but I can not figure out how I would place there using
>the FM interface; and there's *no way* I'm going to place/move hundreds
>of these markers manually!)

No, it isn't a good idea to put it before 
the <title>.  That's where it belongs.

>Project is setup as much as I possibly could in D2G Project Manager--I
>mean, I've checked *everywhere*: every INI file in the stack and every
>tab in the UI. I've added every line of code to the project INI file
>that the D2G Help says is needed for alias files (i.e.,
>'MakeAliasFile=Yes' and 'AliasPrefix=IDH_' and 'UseAliasAName=Yes').

That's all good.

>Press "Start" button... Lo! A CHM file, which opens showing the page to
>which I want it to default. And I go to check in the output folder,
>because "When you use PI markers for CSH destinations, by default
>DITA2Go generates an alias file for you, named after your document, with
>extension '.hha'...". [D2G Help 18.11.4].

The thing is, we don't make the alias files
if we don't see any aliases.  So if we can 
get the PI syntax working, either on your
end or on ours, we'll be fine.

We've recently added about a thousand TopicAlias
markers to the UG itself, to provide full CSH 
for a new utility that manages .ini files; it
will be part of the next release.  And it needs
to work in both Mif2Go and DITA2Go.

Of course, we don't use the structured Frame
setup to produce DITA; we use Mif2Go, which
does create the PIs as we need them in DITA.

>Um, nope. No HHA file in the project folder (nor even on my entire hard
>drive--yes, I searched). So I'm having some doubts that the CHM would
>work, if delivered to the development team, because "If you use PI
>markers for CSH destinations, you need both a map file and an alias
>file". [D2G Help 18.11.2]

Actually... it depends on the Microsoft API
they use to call the Help.  Those files are
needed when they call by the number the
IDH* is defined as in their code.  That's the 
API called HTMLHelp() with the HH_HELP_CONTEXT 
command.  We use the HH_DISPLAY_TOPIC command 
where you pass the filename within the CHM
instead, and that does not need those files.

>Additional note: there is no '#include "My_Project.hha"' line under the
>'[ALIAS]' section of the project's HHP file. I could add one easily; but
>lacking the file to which it refers, it seems pointless at the moment.

Right.

>So I wonder... what is a PI marker, if not what I'm placing? I've tried
>showing every possible element, including invalid ones for the location
>at which I want the marker (before the TITLE element), but I see no "PI"
>element that I could use.

That's why we had to use the XML PIs for it:
  <?target name="value" ... ?>

>Any help? I'd check on the DITA2Go forums, but they seem a bit on the
>dead side. 

We do respond ourselves to posts there.

>So I'm turning to my fellow Framers because, if nothing else,
>I need to be able to do it consistently in FM, not by hacking away with
>a text editor.
>
>Help me with HELP!

The other option, of course, is to use Mif2Go,
which runs from MIF and doesn't care what Adobe
does in the XML.  That would be an instant fix,
but it's not free like DITA2Go.  We couldn't
continue adding nifty features if it were.  ;-)

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