The documentation available from Microsoft does its best to keep you in the dark: They tell you how to generate it in Help Workshop using their point-and-click GUI. It's serviceable but not much fun to use. No wonder there's such a huge cottage industry of MS Help front ends!
Paul Wise bravely documents what he could re-engineer about the innards of the .CHM file but only devotes a rather short section to the Sitemap format of the TOC, which I quote here:
These formats are based on HTML and use the following doctype:<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
The<HEAD>tag contains a<meta>tag providing information on the program that generated the files and a comment indicating the version of the file. e.g.:<meta name="GENERATOR"content="Microsoft® HTML Help Workshop 4.1"><!-- Sitemap 1.0 -->
The<BODY>tag contains an<OBJECT>tag that stores properties of the file in<param>tags, followed by a<UL>tag, whose<LI>tags have<OBJECT>tags that store the properties of the Contents/Index items in<param>tags. e.g.:
<OBJECT type="text/site properties">
<param name="Property Name" value="Property Value">
…
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Property Name" value="Property Value">
…
</OBJECT>
…
</UL>
</BODY>
Note that the Property Names and Property Values and tags are not case-sensitive, but HHW will always write all three in the default capitilization, when appropriate.
Note that the tags are mostly in uppercase and the<LI>tag is not closed; this is in compliance with the doctype.
I spent some days generating the TOC from a different structure. To help with eyeball debugging, my HTML was nicely indented. I started a new line for each tag - not entirely unreasonable. Without the indentation, here's an example of what I created:
<HTML>
<BODY>
<UL>
<LI>
<OBJECT type="text/sitemap">
<param name="Name" value="Heading 1">
<param name="Local" value="h1.htm">
</OBJECT>
</LI>
</UL>
</BODY>
</HTML>
Try as I might, HHW (the Workshop) would not display such a TOC, and HHC (the Compiler) would not produce a working .CHM from it. I spent a long time figuring out what's needed to make it work, as in the following:
<HTML>
<BODY>
<UL>
<LI><OBJECT type="text/sitemap">
<param name="Name" value="Heading 1">
<param name="Local" value="h1.htm">
</OBJECT>
</LI>
</UL>
</BODY>
</HTML>
This appears to be one of the best kept secrets of the HTML Help generating industry:
If you don't put
<LI> on the same line as <OBJECT>, the TOC parser will fail!So the accepted format is essentially an HTML Unordered List of Objects with details in Params, give or take a horrible bug in the scanner/parser.
On the bright side, in my experience the following bits are not essential:
- As Paul states, tags and even attribute names are accepted in upper or lower case.
- The stuff in the
<HEAD>isn't needed and can be dispensed with. - The
text/site propertiesOBJECT is only needed if you want to fiddle with the options - Tags may be consistently closed (XML fashion), including those that HTML is inconsistent about, such as
<meta>and<param. Similarly, it's OK to have closing</LI>'s.
1 comment:
Nice1
Post a Comment