Custom map file not applied to context-sensitive CHM help

You can use a custom map or header file with your HTML Help-based ePublisher projects. Add the *.h file to your project's Files folder, and then open the Format Settings for the HTML Help target. Click the button in the value field of the "HTML help custom map file" field, and choose the appropriate file from the list. Then, regenerate your output. The file should be referenced in the resulting HHP's [MAP] section.

However, in some cases, the file is not referenced correctly, and therefore contextual help is broken. This can occur if your custom map file has one or more spaces in the file name (e.g., "My custom file.h"). When ePublisher processes the file name, the text is escaped for XML, resulting in a value like "My%20custom%20file.h". The HHP looks for a literal match, finds none, and don't connect the dots.

The most simple solution to this issue is to remove spaces from the file name of your custom map file. To fix the problem at the source, you can perform a simple format override:

  • Perform a project format override on a file called htmlhelp_hhp.xsl, located by default in the ePublisher Pro installation directory, here:
    C:\Program Files\WebWorks\ePublisher Pro\Formats\Microsoft HTML Help 1.x\Transforms\

    For details on the override procedure, see the online TechNote article here:

    http://webworks.com/Technical_Assistance/Tech_Notes/Common/EX_ePub_Project_Format_Overrides.shtml

  • Once you have copied the file into the appropriate location in your project directory, open it in a text- or xml-editing application, such as NotePad.

  • Locate the following block of code under the <!-- Map File --> section:

      <xsl:when test="string-length($VarCustomMapFile) &gt; 0">
       <xsl:call-template name="URI-ResolveProjectFileURI">
        <xsl:with-param name="ParamFromAbsoluteURI" select="$VarPath" />
        <xsl:with-param name="ParamSplits" select="$VarSplits" />
        <xsl:with-param name="ParamURI" select="$VarCustomMapFile" />
       </xsl:call-template>
      </xsl:when>
  • Replace that code with this:
      <xsl:when test="string-length($VarCustomMapFile) &gt; 0">
       <xsl:variable name="VarTempMapPath">
        <xsl:call-template name="URI-ResolveProjectFileURI">
         <xsl:with-param name="ParamFromAbsoluteURI" select="$VarPath" />
         <xsl:with-param name="ParamSplits" select="$VarSplits" />
         <xsl:with-param name="ParamURI" select="$VarCustomMapFile" />
        </xsl:call-template>
       </xsl:variable>
       <xsl:value-of select="wwuri:Unescape($VarTempMapPath)" />
      </xsl:when>
  • Save and close htmlhelp_hhp.xsl
  • Regenerate your output to apply the changes.

I have also attached a modified version of htmlhelp_hhp.xsl, should you be uncomfortable making the XSL changes yourself. Download the attached file, create the following folder structure in your project directory, and copy the file there: Formats/Microsoft HTML Help 1.x/Transforms/

Note: the attached file is designed for compatibility with ePublisher 9.3.


CategorySolutionsOutputCsh

Permalinks/Solutions/Output/Context Sensitive Help/CustomMapNotApplied (last edited 2010-04-01 19:25:39 by LaurenLever)