One of the challengers in migrating older help is making changes that do not break older help compiles. One approach is to give Migrate more customizable parsing.
In Build 50 we introduced the KeepH3HeaderTags option. This allowed you to predefined Help 3 tags.
For example you can pre-markup a topic with a help id.
Great for migrating a merged help system, since cross module links can now be hardwired to point to a pre-defined Help 3 link.
But not great for single source. Enter $h3m$ substitution.
Here HTML code stored in a comment is inserted into your code by the mshcMigrate Migrate command.
You simply make a $h3m$ comment immediately before the tag you want to substitute.
Best to show you by example.
If a comment contains $h3m$=xxx then the next tag becomes <xxx>
Migrate converts this to...
The next tag could even be a comment.
So this would produce the same result...
Here we substitute just an attribute value. If a comment contains $h3m$href="xxx" then if the next tag contains href="bbb" then bbb is replaced by xxx.
Migrate converts this to...
It works with any attribute. You can only change one attribute. If you need to change more than one, then use the first form and replace the entire tag.
So at the moment image maps are broken in MS Help Viewer 1.0.
Migrate converts them to the form href="ms-xhelp:///id=Topic-Id" however it seems that MS HV 1.0 only expands abbreviated Id links in <a href=""> tags. Other tags are not transformed by Agent.
A full Id link looks something like this...
Let's say we have
If we pre-defined the help Id of contacts.html as...
Then we could use the following $h3m$href= substitution...
After running Migrate we now have
<area href="ms-xhelp:///?method=page&id=Company.XXX.Contacts&product=vs&productversion=100" alt="Contacts" alt="Contacts" title="Contacts" shape="RECT" coords="6,116,97,184" />
<area href="ms-xhelp:///?method=page&id=Company.XXX.Products&product=vs&productversion=100" alt="Products"
Note: You see we didn't specify a "&locale=en-us" parameter. Most API calls do not require it. If omitted Agent will work out the locale for you. Which is good since the user may be running non-English help.
OK so we could have hardwired the links. But the $h3m$ substitution gives us something approaching single source. The HTML topic will still work in MS Help 2 or HTML Help.
The weak point in the above example is that our links are hardwired to the VS\100\* catalog. This may become a problem in the future.
If you are using Helpwares h3m.js script file (see h3m.js Script File) then you can use product=*&productVersion=* and the script will fill in the current catalog information at run time.
(** NOTE: The product=*&productVersion=* syntax currently works only with <a ..> links)