Linking to a CHM - Some Notes

5-Nov-2004: ShowHelp() Breaks under XP SP2

Have a few reports now telling us ShowHelp() has changed yet again under the release of SP2.

  1. David from Unisys informs me that these links used to work inside a HxS file (MS Help 2).
    JavaScript:showHelp('its:TestHelp.chm::/HTMFilename.htm')
    JavaScript:showHelp('ms-its:TestHelp.chm::/HTMFilename.htm')

    However this link still works
    JavaScript:showHelp('mk:@MSITStore:TestHelp.chm::/HTMFilename.htm')

    The problem has been reported to MS
     
  2. Robert Powell reports that web links now fail
    window.showHelp("http://myServer/help/myHelp.chm")

    This was intentionally done by MS for security reasons. CHMs can only be opened on the local PC.

Some of the examples below you will find no longer work.
 


Some ruff notes on linking to a CHM (local/web).
Test machine: Win98 + IE4SP2/IE5 + HH 1.2

From a source at MS says:

HTML Help 1.x does not have the capability of delivering compressed help over
http. You can point to a .chm on the user's local drive, and you can link to
a .chm for download, but that's as far as it goes. This feature has been
tentatively planned for future versions, as there have been many requests for it.


1. Link to a CHM file - Page pulled into Browser:

This appears to only works with a fully qualified path to the CHM.

(1.a) - Full path to CHM - ** OK **
    ms-its:http://www.helpware.net/htmlhelp/help.chm::/masterfile.htm
    mk:@MSITStore:http:/www.helpware.net/htmlhelp/help.chm::/masterfile.htm
    BUT... This fails from inside a CHM file.
    5-Nov-2004: This now shows a blank page since XP SP2 I thing - * Now Fails *
   

(1.b) - Full path to local CHM - ** OK **
    ms-its:c:/windows/help/fonts.chm::/windows_fonts_overview.htm
    mk:@MSITStore:c:/windows/help/fonts.chm::/windows_fonts_overview.htm

    5-Nov-2004: This will work if you download this page to the local PC

(1.c) - Relative path to web CHM - ** Fails **.
    ms-its:help.chm::/masterfile.htm

    5-Nov-2004: This works from inside a HxS VS Help file. Currently broken under XP SP2

Note: These links work -- However the entire CHM is being downloaded to your cache. First time will take forever. Second time will be quick as it loads from the cache.

(1.d) Link to a topic in a CHM on the web - ** OK **
<A HREF="ms-its:http://www.helpware.net/htmlhelp/hhaxref1.chm::/ocx_ov.htm">Link to a topic in a .chm</a>
Link to a topic in a .chm
5-Nov-2004: This will fail under SP2 * Now Fail *
 

2. Standard Link to a CHM file - download dialog

Without the ms-its: prefix your browser will try and download the CHM
with the standard Open or Save question.

(2.a) - Full path to CHM only - ** OK **
<a href=http://www.helpware.net/htmlhelp/help.chm>
 

(2.a) - Relative path to CHM only - ** OK **
<a href=help.chm>
 

(2.c) - Link to topic in file - ** Fails ** (not expecting this one to work)
<a href=http://www.helpware.net/htmlhelp/help.chm::/masterfile.htm>

 

3. Link to CHM file using window.ShowHelp

You can also link to a CHM (from HTML or CHM Topic) using ShowHelp().
ShowHelp is about the only way you can open a HH window (not just extract a topic)
from a single HTML page. It also works from a CHM based topic, but the CHM
must be local. Window.ShowHelp() does not work for web based CHMs.

 5-Nov-2004: Most remote links now fail under SP2.


Web link does not work:

(3.1) - Link to web CHM using VB link via window.ShowHelp() - ** Fails **
    window.ShowHelp("ms-its:http://www.helpware.net/htmlhelp/help.chm::/masterfile.htm>TP2"
    Same link but Uses JavaScript
 

Local works:

(3.2) - Link to local CHM using VB link via window.ShowHelp() - ** OK **
   window.showHelp('ms-its:D:\UVHelp\SPLIT\help.chm::/masterfile.htm>TP2')
   window.showHelp('ms-its:D:\UVHelp\SPLIT\help.chm')
   BUT... This fails from inside a CHM file. Expected.

   Download the CHM locally if you like and put it in a folder called "D:\UVHelp\SPLIT\"

(3.3) - Same as 3.2 but uses relative path - ** Fails **
   window.showHelp('ms-its:file:///help.chm::/masterfile.htm>TP2')
   window.showHelp('ms-its:help.chm::/masterfile.htm>TP2')

Special Note:
I have to be very very careful here. If I run this file locally first (via 3.2), then the Links 3.1 and 3.2 start firing by bringing up the local file. This is confusing behaviour and is just wrong as far as I am concerned. See Ralphs comments below.

IE5 is a little different. Relative Paths DO work but always use UNIX slashes:

These work..

window.showHelp('C:/EUDORA/ATTACH/al.chm')
window.showHelp('file://C:/EUDORA/ATTACH/al.chm')
window.showHelp('mk:@MSITStore:C:/EUDORA/ATTACH/al.chm')
window.showHelp('Test/al.chm')
window.showHelp('file://Test/al.chm')

These do not work...Sort of. Chm opens but topic cannot be found<br>

window.showHelp('mk:@MSITStore:TEST/al.chm') 
window.showHelp('its:TEST/al.chm')

These do not work..

window.showHelp('C:\EUDORA\ATTACH\al.chm')
window.showHelp('file://C:\EUDORA\ATTACH\al.chm')
window.showHelp('mk:@MSITStore:C:\EUDORA\ATTACH\al.chm')
window.showHelp('mk:@MSITStore:TEST/al.chm')
window.showHelp('Test\al.chm')
window.showHelp('file://Test\al.chm')

Conclusion: For IE5.

1. Must have UNIX slashes not DOS slashes.
2. When mk:@MSITStore: prefix is used the full path must be specified.

So the MS Web site example does not work for IE5 uses since it uses a DOS path.
http://msdn2.microsoft.com/en-us/library/ms644690.aspx


Notes on Using ShowHelp()

window.ShowHelp("ms-its:ChmFile::/Topic.htm>MyWinDef"")

You can use topics and window type definition.
CHMFile can be local or web path. HTML Help 1.2 appears to require a fully qualified path.

ShowHelp() Documentation

http://msdn2.microsoft.com/en-us/library/ms536758.aspx

http://msdn2.microsoft.com/en-us/library/ms533027.aspx


Calling an external HTML file from a CHM topic.

I see there is an example of Linking to files outside a chm up on the HH web site.
http://msdn2.microsoft.com/en-us/library/ms644690.aspx

This seems to work well. When you open an external file, it is loaded in to the current HH window.
See also the Helpware.net external file example.

<p>
<SCRIPT Language="JScript">
function parser(fn) {
  var X, Y, sl, a, ra, link;
  ra = /:/;
  a = location.href.search(ra);
  if (a == 2)
    X = 14;
  else
    X = 7;
  sl = "\\";
  Y = location.href.lastIndexOf(sl) + 1;
  link = 'file:///' + location.href.substring(X, Y) + fn;
  location.href = link;
  }
</SCRIPT>
</p>

<p>
<a onclick="parser('test.htm')" style="text-decoration: underline;
color: green; cursor: hand">Link to test.htm</a>
</p>

From: Ralph Walden <ralphw@EXMSFT.COM>
Subject: Re: Link from browser web to CHM
To: WINHLP-L@ADMIN.HUMBERC.ON.CA

Let's say you've got a link to something like: its:myfile.chm::/foo.htm

If you display that link within an HTML Help window, HH will go off and find the location of myfile.chm, turning the link into something like:
its:c:\somefolder\myfile.chm::/foo.htm

However, if you try that first link in the IE browser, it will fail because the browser doesn't know where myfile.chm is located. Somehow or other, you must tell the browser where the "myfile.chm" is located. You can do that with script (Jerry Mead posted a method a while back), you can hard-code the path, or you can install KeyFndHH (a free utility available on www.keyworks.net). The caveat with the latter method is that anytime you install HTML Help, it will blow away KeyFndHH requiring you to re-install it. So your safest method is to hard-code the path, and if that isn't possible, use script, and if that still doesn't work, then use KeyFndHH and make certain your user's know how to re-register it if HH blows it away.


From: Rob Cavicchio <robert.cavicchio@stac.com> 
Subject: showHelp documentation

I've got some more showHelp() info. that you might like to add to your
Web site. I was trying to use showHelp() from within a .CHM to link to
2 different files: (1) the .CHM that contained the file I was linking
from (so I could open a new instance of the same Help file), and (2) the
Internet Explorer Help file. Our file was included in the registry
under the normal ...Windows\HTML Help. In both cases I started with the
syntax "window.showHelp('HelpFile.chm');".

Here's what I found.

(1) To open another instance of the same .CHM file, you need to get the URL
and pass it back as a full path to showHelp(); e.g., "showHelp('c:/program
files/my program/my help.chm')". If you just specify the file it seems to
work from an uncompiled HTML file as long as it is registered, but it still
does not work from within the .CHM. In that case IE 4 SP 1 looks for the
.CHM that you try to link to *within* the .CHM that you link from, in the
same compiled folder that contained the HTML file; while IE 5 successfully
opens the file, but displays the "Page cannot be displayed" page.

(2) With IE 5, you can link to Internet Explorer Help with
"showHelp('iexplore.chm')" from all contexts.

(3) With IE 4.01 SP 1, you can link to IEXPLORE.CHM from an uncompiled
file but not from a compiled file, unless you know the full path to it.
(I tried using "file://iexplore.chm" and "mk:@MSITStore:iexplore.chm",
but neither one worked.)

Rob Cavicchio
Stac Software, Inc.
robert.cavicchio@stac.com


Hi Trey

Work arounds... Mmmm... And hey its my pleasure to chat with you. This is bleeding edge stuff and it really helps if we can all share our ideas. Some of the things done so far MS never even imagined at the time of writing.

-------- Hope this does not bore you too much ------------

=== Have been playing <g>

I just took the help file hhaxref.chm and put it on the web
http://www.helpware.net/htmlhelp/hhaxref1.chm
128K

Next I made several small CHMs that call the above.
1 stays on web, 2.5 must be run locally (open or download).

== Play thing 1 ==

I made a copy of the chm and completely gutted it of
image and htm files. I made all the TOC links point to the
chm on the web.

http://www.helpware.net/htmlhelp/hhaxref2.chm
17K

Click the link above and select open. It opens quickly being small.
Click on the TOC items and initially it appears to lockup while it
downloads the entire CHM to the Cache. After that each link loads
quickly.

== Play thing 2 ==

http://www.helpware.net/htmlhelp/hhaxref3.chm
12K

I further guttered the chm so it contained only one TOC item
plus a merged file item pointing to the HHC in the big CHM on the web.

<OBJECT type="text/sitemap">
<param name="Merge" value="http://www.helpware.net/htmlhelp/hhaxref1.chm::\HHOCX_c.hhc">
</OBJECT>


It is is very quick to load only because the main CHM is already in the cache. From part 1. If you clear the cache first you will see nothing on screen for a minute or two while the TOC is pull off the web site - then the window suddenly appears and all topics are available.

== Play thing 3 ==

http://www.helpware.net/htmlhelp/hhaxref4.chm
12K

This simply defines a plain HH Window - no TOC.

http://www.helpware.net/htmlhelp/hhaxref5.chm
13K

Another test - simple TOC.

========================================================================

What have I learned

1. You cannot open a Web CHM from a HTML DOC but you can from another CHM.

2. You can make a small CHM to download or distribute, that calls
a larger web based CHM.

3. Web Based CHM are very crippled - Cannot see the Window Definitions
of a web based CHM. Thus -- all window definitions and TOC need to
be on the client side.

4. Merge web based HHC works OK. For Intranet the frozen download would
be quick and not so much a problem.

========================================================================

Well theres my play time for the night.
Tell me if have any brain storms

Cheers
Robert