Help 2 Filtering

Topics: User Forum
Jul 20, 2007 at 2:20 AM
I have integrated a Help 2 file generated by SHFB into the Visual Studio Combined Help Collection. But I would like to add a filter for my help file to the "Filtered by" drop-down list in Microsoft Document Explorer, the utility that is used to view Help 2 documentation.

My requirement is relatively simple. At this stage I do not need multiple filters for different sets of classes within my help file. I just want a single filter for the whole help file. Users could then select the filter for my help file in the "Filtered by" drop-down list to only show items from my help file in the Visual Studio Combined Help Collection's Contents and Index.

A similar request was raised in the DocSet filtering item http://www.codeplex.com/SHFB/WorkItem/View.aspx?WorkItemId=8886
in SHFB's Issue Tracker. Eric's comment was
This would involve modifying the transformations that come with Sandcastle itself and is beyond the scope of the help file builder. Please post your request in the MSDN Documentation Forum.
So I had a look in the MSDN Documentation Forum and found a suggestion in the Sandcastle feature requests thread http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=944516&SiteID=1. The thread initiator asks, amongst other things, for an easier way to specify the DocSet attributes that are used to control filtering. However, he apparently has a work-round:
I create a "specific_content.xml" file containing things like header, footer, title, docset etc.
If I've understood this correctly, maybe there is a way SHFB could be enhanced to allow a single filter to be defined for the Help 2 file being generated. There could be a new project property called something like FilterName. The DocSet attribute required for the filter would be generated from this. Presumably this would be in a format similar to the Defining Attributes examples shown in http://helpware.net/mshelp2/attribs.htm#basics except that in this case we would be writing the attribute to an XML file for input to Sandcastle rather than to an HTML file. I think SHFB may already generate a suitable special XML file to which the attribute could be added.
Coordinator
Jul 20, 2007 at 5:12 AM
No, he's refering to the user-definable items such as the header and footer text and not the MSHelp attributes. specific_content.xml in this case is equivalent to SHFB's SharedBuilderContent.xml. It just overrides existing <item> entries in the stock content files with alternate text. Any duplicate items in files that appear later in the list replace the content from the stock files. That's how SHFB replaces the default header, footer, and preliminary messages among other things.

You could certainly put the <item> tags in the shared content files to define the MSHelp tags but in order to get them in the help topics you still have to modify the transformations to render <include> tags that get replaced by the shared content. Until that happens, it can't be supported with a project property.

Eric
Jul 20, 2007 at 9:52 PM
Hello Eric,

The MSDN Documentation Forum thread does specifically mention putting DocSet attributes in the shared contents file, which is why I mentioned it. Also, after I started this thread, I found another thread in this forum where a slightly different workaround that is claimed to work with SHFB is suggested: How to attach DocSet attribute to the resulting HxS file?http://www.codeplex.com/SHFB/Thread/View.aspx?ThreadId=8374. I tried the workaround that is suggested there, but it did not work for me.

So people seem to be claiming to be able to do this, yet your knowledge of the technology and my empirical experience say it does not work. Or am I missing a point?

Cheers,
Simon
Sep 3, 2007 at 2:38 AM
I've got this working at last! See the discussion that has been added to http://www.codeplex.com/SHFB/Thread/View.aspx?ThreadId=8374.