HelpContextID

Topics: Developer Forum
Sep 9, 2011 at 10:30 AM

Hi,

I'm part of a project where we're migrating a very old and very huge VB6 application to more up-to-date standards. Part of this project is, of course, to migrate the help system.

I would like to move the entire help system to Sandcastle and use SHFB to manage it; but unfortunately, it seems that this cannot be done. VB6 uses a number called HelpContextID to lookup help topics in a HtmlHelp1 file, and the mapping between actual topics and these IDs are defined in the project file used to build the HtmlHelp1 file.

Would it be possible to include these mappings in the SHFB project in some way? Could we create a plugin or something like that to handle it? All we need is a way to add the mapping as an attribute in the topic file, and then having this attribute included as a mapping in the HtmlHelp1 project file.

Regards,
Lars

Coordinator
Sep 10, 2011 at 8:13 PM

Adding support for a new ID type probably isn't necessary.  You can open the help file and show a specific topic by passing in the filename created from the topic's ID.  For example, I open SHFB help topics in the following manner:

Form form = new Form();
form.CreateControl();
Help.ShowHelp(form, pathToHelpFile, HelpNavigator.Topic,
    "html/7df16a60-f718-4b8f-bfa2-88c42906070c.htm");

Opening any other topic is just a matter of replacing the filename with "html/" + [topic GUID] + ".htm".

Eric

 

Sep 12, 2011 at 6:42 AM

Hi Eric,

Right you are: However, that would mean that we would have to edit thousands of VB6 forms by hand - the HelpContextID is stored in the binary *.frx, not the human readable *.frm file.

That's why I would prefer a way to keep our present IDs.

Regards,
Lars

Coordinator
Sep 12, 2011 at 6:12 PM
Edited Sep 12, 2011 at 6:14 PM

If the ID ends up in the HTML for the topic, you could probably add a custom element to the MAML topic to specify the existing ID and then write it out to each HTML topic as part of the XSL transformations.  The following topic discusses how to add custom sections and elements for API topics but the process would be similar for MAML elements.  You'd just place it in a different XSL transformation.  The Presentation\Shared\utilities_dduexml.xsl is probably the best bet.

http://blogs.msdn.com/b/sandcastle/archive/2006/11/22/supporting-custom-tags-in-sandcastle.aspx

If not stored in the topics and they are part of the compiled help project file, you'd need to write a plug-in for SHFB that lets you extract the IDs in some manner (i.e. from an extra attribute on the topic element in each file) and add them to the .hhp project file just prior to it getting built.  See this topic for more information:  http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/a14e026e-642f-4ce6-9506-341e57cc3d1f.htm

Bear in mind the SHFB and Sandcastle are geared more towards documenting assemblies rather than creating help files for end-user/line of business applications.  While possible, it may not be the best choice.

Eric

 

Sep 13, 2011 at 11:08 AM

Hi Eric,

Thanks for your prompt reply.

EWoodruff wrote:

Bear in mind the SHFB and Sandcastle are geared more towards documenting assemblies rather than creating help files for end-user/line of business applications.  While possible, it may not be the best choice.

I do understand your concerns - however, my rationale is the following: The company I work for haven't been too serious about documenting the code. Up till now: I'm going to teach the developers how to document their code and as part of that we're going to build a complete documentation set every night. Automated, of course. Anyway, our developers will have to learn how to handle XML documentation, MAML etc.

But we also need an updated way to create help files for our products: Coming from the VB6 world, we have a very oldfashioned way of creating help files. So I thought that it might be a better idea only to teach the developers one way of creating documentation and help files instead of having to teach them two different ways of doing essentially the same task?

I'd been looking for a description of how to create a plugin for SHFB - thanks for pointing me in the right direction. :-)

Regards,
Lars