HelpCenter/Tips/HTML_Help_LinkToCHM

Creating Links to CHM Files

Recent security updates from Microsoft have made it increasingly difficult to link to and from compiled help files (CHM). This page will offer some tips and resources relating to launching and referencing CHM files.

Linking to Topics in Merged Help

In a merged helpset, ePublisher will create a Master CHM as well as a separate CHM for each project Group. All of the CHM files must be distributed together, as the merge is done at runtime when you launch the Master file. To create a link from one child CHM to a specific topic file in another, we recommend this procedure:

In the first CHM, add a link with a URL as follows:

ms-its:File.chm::/filename.html
- Where "File.chm" is the name of the child CHM to which you are linking (all files must be in the same directory), and "filename.html" is the reference to the topic's HTML file. It is helpful for this reason to use filename markers to name your output files.
- Note: FrameMaker users will create a hypertext marker like this:
  - message URL ms-its:File.chm::/filename.html

This syntax is referenced in Microsoft's developer web article here:

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

The link must open the designated topic file in the current HTML Help window. Security limitations prevent a CHM file from launching a new HTML Help window. To ensure this, open Format Settings in your ePublisher project and set the External URL Target to "_self" before regenerating output.

Linking to Another (Unrelated) CHM

It is possible to create a link from one CHM to another, other than in a merged helpset. However, you need to keep a couple of things in mind:

You must know the complete local path to the destination CHM file. This, of course, can be difficult with help systems installed on an end user's machine.
You cannot open a CHM from a remote or network location. This again causes problems because you can't effectively store the CHM on a public web server, either.

If the file is stored locally and you know the full path, we have found this link URL will work for opening topics in another CHM:

ms-its:file:///C:/Documents & Settings/User/Desktop/File.chm::/Filename.html
And replace the appropriate path and file names with your own values.

Note: This syntax differs from that specified in Microsoft's developer reference article here:

http://msdn2.microsoft.com/en-gb/library/ms644582.aspx

This will open the topic from the second CHM in the current HTML Help window. Again, you'll need to specify this by opening the Format Settings in your ePublisher project and setting the External URL Target to "_self" before regenerating output. Note also that the TOC and Index will remain the same (referencing the first CHM).

Resources

Here are some helpful links to Microsoft web pages offering details regarding the problems you might face with CHM links and the solutions provided here:

http://support.microsoft.com/kb/896358 - The July 2006 Windows update which may cause problems for CHM output.

Late Night Merge Attempt

This is not a complete solution. Just a starting point for automating this task. It might be better to create a data file to read which defines a list of additional .chm files to reference when producing the final merged .chm file.

Override "Transforms/htmlhelp_hhp.xsl" and look around line 353 of the root match template:

 <xsl:template match="/">
 ...

        <xsl:variable name="VarMergeFiles" select="key('wwsplits-files-by-type', $ParameterCHMSplitFileType)" />

Have this transform search not just for ePublisher generated CHM files, but also for any .chm files that are coming along for the ride in your <project>/Files or baggage files folders by replacing the existing <xsl:variable name="VarMergeFiles" ... /> definition with:

        <xsl:variable name="VarMergeFilesAsXML">
         <!-- Generate CHM files -->
         <!--                    -->
         <xsl:copy-of select="key('wwsplits-files-by-type', $ParameterCHMSplitFileType)" />

         <!-- Baggage and copied (project folder/Files) files -->
         <!--                                                 -->
         <xsl:variable name="VarBaggageAndCopies" select="key('wwsplits-files-by-type', 'baggage') | key('wwsplits-files-by-type', 'copy')" />
         <xsl:for-each select="$VarBaggageAndCopies">
          <xsl:variable name="VarSplitFile" select="." />

          <!-- Filter based on '.chm' extension -->
          <!--                                  -->
          <xsl:variable name="VarSplitFileExtension" select="wwfilesystem:GetExtension($VarSplitFile/@path)" />
          <xsl:variable name="VarSplitFileExtensionToLower" select="wwstring:ToLower($VarSplitFileExtension)" />
          <xsl:if test="$VarSplitFileExtensionToLower = '.chm'">
           <!-- Found another .chm file! -->
           <!--                          -->
           <xsl:copy-of select="$VarSplitFile" />
          </xsl:if>
         </xsl:for-each>
        </xsl:variable>
        <xsl:variable name="VarMergeFiles" select="msxsl:node-set($VarMergeFilesAsXML)/wwsplits:File" />

This code will save you from having to edit/modify the merged .hhp file to include your other .chm files.

NOTE: Presently, this only triggers if you're got more than one top-level group defined in ePublisher. ePublisher won't otherwise emit the merge .chm. Also, this will replicate the .chm files across your individual outputs. More work needed to copy them to the top-level of the project and ignore them as lower level files.

HelpCenter/Tips/HTML_Help_LinkToCHM (last edited 2009-03-25 17:53:55 by BenAllums)