Blog‎ > ‎

mshcMigrate build 55/56 - Substitution

posted May 8, 2010, 6:30 AM by Robert Chandler   [ updated May 9, 2010, 11:18 AM ]
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.

<meta name="Microsoft.Help.Id" content="Helpware.FAR.GettingStarted" />

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.

$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.

Example: $h3m$=xxx

If a comment contains $h3m$=xxx then the next tag becomes <xxx>

<!-- $h3m$=a href="ms-xhelp:///id=Helpware.FAR.GettingStarted" -->
<a href="GettingStarted.htm">

Migrate converts this to...

<a href="ms-xhelp:///id=Helpware.FAR.GettingStarted">

The next tag could even be a comment.
So this would produce the same result...

<!-- $h3m$=a href="ms-xhelp:///id=Helpware.FAR.GettingStarted" -->
<!-- This dummy line will be replaced during migrate -->

Example: $h3m$<attribute>=xxx

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.

<!-- $h3m$href="ms-xhelp:///id=test123" -->
<a href="demo" target="_blank" />

Migrate converts this to...

<a href="ms-xhelp:///id=test123" target="_blank" />

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.

Advanced Example

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 

<map name="map1">

   <area href="contacts.html" alt="Contacts" 
    title="Contacts" shape="RECT" coords="6,116,97,184" />

   <area href="products.html" alt="Products" 
    title="Products" shape="CIRCLE" coords="251,143,47" />

If we pre-defined the help Id of contacts.html as...

<meta name="Microsoft.Help.Id" content="Company.XXX.Contacts" />

and products.html as...

<meta name="Microsoft.Help.Id" content="Company.XXX.Products" />

Then we could use the following $h3m$href= substitution...

<map name="map1">

   <!-- $h3m$href="ms-xhelp:///?method=page&id=Company.XXX.Contacts&product=vs&productversion=100" -->

   <area href="contacts.html" alt="Contacts" 
    title="Contacts" shape="RECT" coords="6,116,97,184" />

   <!-- $h3m$href="ms-xhelp:///?method=page&id=Company.XXX.Products&product=vs&productversion=100" -->

   <area href="products.html" alt="Products" 
    title="Products" shape="CIRCLE" coords="251,143,47" />

After running Migrate we now have 

<map name="map1">

   <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" 
    title="Products" shape="CIRCLE" coords="251,143,47" />


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.

Advanced Example Part II

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)

Summing Up

$h3m$ substitution turns the Migrate command into your personal parser. It solves problems such as single source and migrating cross module links.

If you have more ideas on improving Migrate please let me know.