Adding additional Help 1.x content

Sep 4, 2008 at 12:15 AM
I'm trying to add additional Help 1.x content (reference, not conceptual) so that my manually created .htm files show up in the output. I created a folder called "MoreHTML" with my HTML files and added it to the list of included folders. When I build the help file I can find my topics by searching but they don't show up in the index or contents so I hand-edited the index and content files (hhk an hhc). Now my pages show up in the content and index but when I rebuild my DocProject from scratch naturally my entries are gone.

My question: is there any way of merging my hand-added entries with the index and content files generated by DocProject? Alternatively, is there an easy way to merge two Help 1.x projects?

By the way, the reason I'm doing this is to support a work-around for non-managed C++ help files. I moved my unmanaged headers with XML comments into a fake managed project, used DocProject to generate the entire Help 1.x structure and now I'm planning on fixing up the incorrect references to .NET types (e.g. get rid of inheritance from System.Object, etc.). This will give me a good base for my reference documentation and I don't have to do everything by hand.


Sep 4, 2008 at 12:47 AM
Hi Andrew,

Topic Explorer actually supports HTML topics just like MAML topics, although I think that the Topic Import dialog doesn't have an .htm file filter by default, IIRC.  In that case you can enter *.htm into the text box and then press Enter - that will cause the dialog to show all .htm files that you may choose from to import into the project.

Alternatively, you can edit the Help\Settings\topics.xml file manually to include your HTML files.  They should be stored in your project's Help\Topics\Html folder or a custom subfolder under that path.  Then you can press the refresh button in Topic Explorer and drag & drop your raw HTML topics as if they were MAML topics to organize the TOC.

Each of your raw HTML files should contain an XML data island that specifies the desired MS Help 2.x attributes.  DocProject runs the HTML files through the ChmBuilder tool, which analyzes the Help 2.x attributes to generate the Help 1.x index file.

I suggest opening an auto-generated HTML file for an actual API and you'll see the <xml> element in the header that you can use as a reference.  Also, here's the documentation for Help 2.x, but note that the ChmBuilder probably only uses a subset of the information (I think that K-index keywords are probably all that you'll need to specify): 

Help XML Reference 

Your solution for documenting C++ seems like a good one for now, at least until the Sandcastle team introduces native C++ support in Sandcastle (assuming that will happen ;)

- Dave
Sep 4, 2008 at 12:55 AM
Great, it sounds like that will give me what I'm looking for!