FAQ‎ > ‎

HV 1.0 Links

This page explore the links within a Help Viewer help topic.
Before starting you may want to read: Help API, F1 & URLs

Help Library Agent

In MS Help 1.0 each topic is given a unique help ID and optionally a unique F1 context Id. These Ids are used to link between topics.

<meta name="Microsoft.Help.Id" content="SomeUniqueId" />
<meta name="Microsoft.Help.F1" content="myContextID" />
<meta name="Microsoft.Help.SelfBranded" content="true"/>

When a .mshc help file is installed, it is copied into the Help Library store exactly as you authored it. Yet when you do a "View Source" (browser) you will see your topic source heavily modified. The extent of the modifications depend on whether the topic is marked as SelfBranded or not.

Agent is responsible for fetching content from the store, modifying it and passing it to the help viewer. Some modification are done via branding package transforms. Others appear to be done directly by the agent application.

<a href="ms-xhelp:///?id=xxx"> Links

This simple Id link is the most common way of linking between help topics. Agent uses a transform to expand <a href="ms-xhelp:///?id=xxx"> links to the full URL at render time.

So tags like this in your source code...

<a href="ms-xhelp:///?id=RWCTest1">

Or like this...

<a href="ms.help?id=RWCTest1">


Are expanded by Agent at render time to this...

<a href="ms.help?method=page&id=RWCTEST1&product=VS&productVersion=100&topicVersion=&locale=EN-US&topicLocale=EN-US" target="">

If you do a "View Source" in your browser and that's what you'll see. 

Advantage of Transform: 
  • Simple. Just specify the ID. The help system adds the current catalog info for you. 
  • You help works with any catalog.
Disadvantage:
  • The transform only works on <a href=""> tags.
  • Only useful for simple links (with no bookmarks) between topics.
  • Currently the transform cannot handle bookmarks. 
    • <a href="#bookmark"> is given an unwanted target="" (a bug in HV 1.0). 
    • <a href="ms-xhelp:///?id=xxx#bookmark" > produces broken link as the bookmark is placed after the Id in the expanded path (it should be at the end of the URL).

ms-xhelp:///? VS ms.help?

Not sure that I see any obvious advantage in using one or the other. Differences:
  • At topic render time Agent replaces every occurrence of text "ms-xhelp*?" with something like "http://127.0.0.1:47873/help/0-11036/ms.help?". A format understood by browsers.
  • URLs using ms-help? are not modified. And somehow when you click on these links Agent is able to navigate you to the correct topic.
  • Microsoft themselves use ms.help? prefix a lot.
One small advantage of ms.help? link over ms-xhelp:///? is that Agent wont modify ms.help? links (except for <a href="ms.help?id=xxx"> - see above). So your scripting is simplified a little.

Making a Redirection Link

These solutions work for both SelfBranded=true and SelfBranded=false.

Here's a redirection link using a help Id (Page API call). Insert this anywhere in the topic header.
(see test topics testdoc3.htm and testdoc4.htm -- attached)

<meta http-equiv="refresh" content="0; url=ms-xhelp:///?method=page&id=RWCTest1&product=VS&productVersion=100">

or use the "ms.help?" form if you want
(see test topics testdoc7.htm and testdoc8.htm - attached)

<meta http-equiv="refresh" content="0; url=ms.help?method=page&id=RWCTest1&product=VS&productVersion=100">

Notice I had to specify target catalog but not the catalog locale ("&locale=en-us" parameter). MS HV 1.0 is smart enough to work out the locale (for both Page and F1 API calls). Which is good because your customer could have installed say French VS and help catalog = VS\100\fr-fr instead of VS\100\en-us.


You could also use the "F1" API call. Again locale is not required.
(see test topics testdoc5.htm and testdoc6.htm - attached)

<meta http-equiv="refresh" content="0; url=ms-xhelp:///?method=f1&query=RWCTest1&product=VS&productVersion=100">

or use the "ms.help?" form if you want

<meta http-equiv="refresh" content="0; url=ms.help?method=f1&query=RWCTest1&product=VS&productVersion=100">


Advantages
  • Using redirection file you can add duplicate TOC items (normally not allowed in HV 1.0). However TOC sync (if supported by the viewer) will only find the one occurrence.
Disadvantages
  • You need to specify the the target catalog (locale optional). So not flexible as only works for hardwired catalog (unless you do some very fancy DOM manipulation using scripting).


April-2010 - h3m.js

  • We now ship a script file that expands the capabilities of MS HV Links, and fixes bookmarks link broken by HV 1.0. See h3m.js Script File
Subpages (1): <img> Notes
ċ
LinkTest.zip
(153k)
Robert Chandler,
Aug 4, 2010, 12:38 AM
Comments