This project has moved and is read-only. For the latest updates, please go here.

How to manage several versions of Help files

Topics: Developer Forum
Feb 6, 2009 at 1:02 PM
I know that this question is not directly related to SHFB, but I have really no idea how to do and I guess people using SHFB could give me some good tips.

Until now, I had one version of my application "MyApplication 1.0."
To generate MS Help 2.0 documentation for MyApplication 1.0, I am using Sandcastle, SHFB, FAR and H2Reg.exe
I have also modified the "utilities_metadata.xsl" file from Sandcastle to add a DocSet tag (Value="MyApplication 1.0") and be able to filter on my "MyApplication 1.0" in MS Document Explorer.

As of now, I will deliver a new version of my application: "MyApplication 1.1".

Both "MyApplication 1.1" and "MyApplication  1.0" can be installed on a PC.
So I would like to also be able to install help files for those two versions side by side.

I have therefore duplicated all the output files of FAR and used distinct filter names and DocSet values in those files.
I have also set dynamically a distinct DocSet Value in the "utilities_metadata.xsl" file depending on the help that I am generating.

But this does not seem to be enough. When I install the help files of "My Application 1.1", I can't find any help topic for "My Application 1.0" anymore in the MS Document Explorer.

I am far from an expert in MS Help 2.0 !

Could you help me to identify which FAR "parameters" make a help file distinct from another one,both beeing related to the same application ?
Ex.: I didn't change  in the FAR's input/output files:
- the name of the generated HxS files,
- the namespaces used in theH2Reg_cmd.ici file,
- the Url used in the Help TOC, because I am unsure about their purpose.

Should I also change various parameters in my .shfb files ?
Ex.: I have only changed the HelpFileVersion:
-  <HelpFileVersion></HelpFileVersion>
But I have kept the same RootNamespaceTitle, HelpTitle, HtmlHelpName:
-  <RootNamespaceTitle>My Application</RootNamespaceTitle>
-  <HelpTitle>My Application</HelpTitle>
-  <HtmlHelpName>My.Application</HtmlHelpName>

Thanks in advance for any help, suggestion or link on a website/blog discussing about this topic would be welcome!


Feb 6, 2009 at 4:31 PM
Edited Feb 6, 2009 at 4:32 PM
Rather than modify the XSL transformation to add the custom attributes, use the project's HelpAttributes collection as that will do it for you in each project.  You should also go into the editor for it and hit the Default button so that it adds the required default attributes too for Help 2 files.

Another option is to use the Version Builder plug-in which allows you to merge information about which version a class or member appears in into the help topics.  That way, you wouldn't need two help files, just the one with version info merged into it sort of like the .NET Framework help.  See the plug-in help topic for more information on using it.

Feb 9, 2009 at 8:25 AM


I already has this in the HelpAttribute collection (I will check the Default button of the editor (I assume you mean the FAR's one ?) to add the other attributes):



AttName Id="1" Name="DocSet" Display="Yes" UIString="MyApplication 1.1" AttType="Enum">
AttVal Id="1_1" Name="MyApplication 1.1" Display="Yes" UIString="MyApplication 1.1" />



But this filter does not work in the MS Doc Explorer except if I manualy add the DocSet into the XSL transformation.

Anyway, I will look for the "version builder plug-in". Thanks a lot for this suggestion !


Feb 9, 2009 at 4:22 PM
No, I'm referring to the property editor for the HelpAttributes property in the SHFB project.