Thursday, September 27, 2007

HHC help file format gotcha

back in my days working with NCompass Resolution and Microsoft Content Management Server (MCMS), I began an MCMS FAQ that was published in CHM and HTML formats. I used to write the topics in Resolution (and later in MCMS) and then I had my ASP script that dynamically produced an HHC table of contents so that Microsoft Help Workshop could create a full-text search version of the document.

well that was back in about 1999 and I obviously didn't remember all the lessons from back then. today I was working with basically the same setup (minus MCMS) for Metalogix Software's SharePoint migration solutions.

I was creating a new CHM and found that Help Workshop will compile the file, but the result was, "This program cannot display the webpage".

I found the answer after looking at the broken .HHC file and a working file side-by-side. so here's my little test. can you see the difference?

this is a--greatly simplified--broken .HHC file:

<html>
<head>
<!--Sitemap 1.0-->
</head>
<body>
<ul>
<li><object type="text/sitemap">
<param name="Name" value="Foo Directory">
<param name="Local" value="Foo Directory/index.htm">
<param name="ImageNumber" value="1">
</object></li>
<ul>
<li><object type="text/sitemap">
<param name="Name" value="Topic1">
<param name="Local" value="Foo Directory/Bar.htm">
<param name="ImageNumber" value="11">
</object></li>
<li><object type="text/sitemap">
<param name="Name" value="Topic1">
<param name="Local" value="Foo Directory/Foo.htm">
<param name="ImageNumber" value="11">
</object> </li>
</ul>
</ul>
</body>
</html>

and here is a working .HHC file:

<html>
<head>
<!--Sitemap 1.0-->
</head>
<body>
<ul>
<li><object type="text/sitemap">
<param name="Name" value="Foo Directory">
<param name="Local" value="BarDirectory/index.htm">
<param name="ImageNumber" value="1">
</object></li>
<ul>
<li><object type="text/sitemap">
<param name="Name" value="Topic1">
<param name="Local" value="BarDirectory/Bar.htm">
<param name="ImageNumber" value="11">
</object></li>
<li><object type="text/sitemap">
<param name="Name" value="Topic1">
<param name="Local" value="BarDirectory/Foo.htm">
<param name="ImageNumber" value="11">
</object></li>
</ul>
</ul>
</body>
</html>

answer below...


- click for full-size image

answer: the help file directories must not contain spaces in their names. "Foo Directory" will fail, "BarDirectory" will work. now that's a gotcha that the app should catch and report.

BTW - this same error will appear if you don't select a "Default file" inside the Help Workshop project options. however, in that case, everything works once you click on a topic.

No comments: