Help 2 Table of Contents Disappears

Topics: User Forum
Feb 19, 2008 at 1:42 AM
After upgrading SHFB to version 1.6.0.4 and Sandcastle to January 2008, I find that my SHFB project no longer generates a Help 2 table of contents. It had worked fine when built with SHFB to version 1.6.0.2 shortly before I upgraded the software. If I create Help 1 output instead of Help 2, the Help 1 table of contents is still created fine.

I have not tried backing out my SHFB/Sandcastle software upgrade. So I cannot be certain that the software upgrade is relevant. I could try doing a backout if that would help diagnose the problem. In any case, I would appreciate some advice on how I can fix this.

I have already narrowed it down a bit, I think. Using Far HTML to examine the Microsoft Help Collection Definition File (*.HxC) generated by SHFB/Sandcastle, I found that no Table of Contents file is was assigned to the Collection. Surely the *.HxT file that was also generated by SHFB/Sandcastle should have been assigned as the Table of Contents file for the Collection?

Simon
Coordinator
Feb 19, 2008 at 2:34 AM
It works fine when viewed with the freeware H2 Viewer. I haven't gone as far as integrating it into a collection though. The only thing that changed was the addition of the NamedUrlIndex file.

Eric
Feb 19, 2008 at 2:51 AM
OK, I've just tried it with H2 Viewer. I get the same problem. If I've done something wrong, I wonder what it is.
Feb 20, 2008 at 1:31 AM
Although I still do not know why the table of contents disappeared, I have been able to get it back. Here's what I had to do.

1) Delete the *.HxC file generated by SHFB and generate a replacement with the H2 Collection Wizard in FAR HTML:
• Use the *.HxS file that was generated by SHFB as the help project.
• Overwrite the *.HxT that was generated by SHFB.
• Auto-register.

2 ) Make the new *.HxC and *.HxT files read-only so that SHFB won't overwrite them in a subsequent build.
Apr 9, 2008 at 1:06 AM
Is there a fix in SandCastle for this issue? I am running into this now and it is hurting my head :(
Coordinator
Apr 9, 2008 at 2:45 AM
Edited Apr 9, 2008 at 2:48 AM
I haven't seen the issue. Better support for Help 2 files will be in the next release. This includes integrated support for generating a valid set of collection files, an H2Reg.ini file, and the ability to add additional attributes to the API topics such as DocSet so that filtering will work as expected.

If you can send me a sample project that demonstrates the problem described above I can look into it and see if I can reproduce the problem with 1.6.0.4 and verify that it doesn't happen with the next release. My e-mail address is in the About Box and the footer of the pages in the help file.

One thing to note: All versions of SHFB so far produce collection files that include the DTD declaration used during compilation. In order to be used, you do need to edit them to remove the DTD (the "SYSTEM" and the URL parts). I do know that can cause some issues if you don't take those bits out. As noted, this is corrected for the next release.

Eric
Coordinator
Apr 18, 2008 at 8:31 PM
Edited Apr 18, 2008 at 8:36 PM
For anyone following this thread, here is the solution:

As expected, the problem is caused by invalid collection files produced by SHFB 1.6.0.6 and earlier. To fix the issue for the time being, do the following:

1. Edit each collection file and delete the word "SYSTEM" and the URL from the DOCTYPE tag.

2. In the .HxC file, delete the <CompilerOptions> element.

3. Replace the content of the .HxT (table of content) file with the following:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE HelpTOC[]>
<HelpTOC DTDVersion="1.0" LangId="1033" PluginStyle="Hierarchical"
    PluginTitle="[HelpTitle]">
  <HelpTOCNode NodeType="TOC" Url="[HtmlHelpName]" />
</HelpTOC>

Step 3 will correct the "missing TOC" issue. Substitute your project's HelpTitle property value for [HelpTitle] and your project's HtmlHelpName for [HtmlHelpName] in the example above. If not using English, replace the "1033" with an appropriate LCID too (see the .HxC file for the value).

Be sure that your HtmlHelpName property value does not contain spaces. They are not allowed in the collection name.

I'm happy to report that the next release of SHFB already does all of the above automatically so this will not be an issue going forward.

Eric
Apr 21, 2008 at 2:47 AM
Good work, Eric. I'm looking forward to checking out the various Help 2 enhancements.

I've followed along your workaround and I can confirm that you are achieving almost exactly the same effect by manually editing the files that I was getting by regenerating them with FAR HTML. The only difference I can see is that the .HxT (table of contents) file that I generated has
LangId=""
instead of
LangId="1033"
as specified by your Step 3.

Just to clarify, it seems to me that where your Step 1 refers to "each collection file", this actually means the .HxC file, the same file as is referred to in your Step 2.

Simon
Coordinator
Apr 21, 2008 at 3:28 AM
There are a set of collection files: an .HxC file (collection) , an .HxT file (TOC), and several .HxK files (index files). All contain the DTD declaration in the DOCTYPE element for compilation but once compiled, it needs to be removed in all of them. Only the .HxC file has a <CompilerOptions> element. The LangId in the SHFB files is set from the Language project property. It probably either isn't set or isn't used in FAR and thus the blank value. If blank or omitted, I think it defaults to English anyway which is what the LCID 1033 represents.

Eric