How to attach DocSet attribute to the resulting HxS file?

Topics: Developer Forum, Project Management Forum, User Forum
Mar 20, 2007 at 12:31 PM
I need to create MSDN style help and integrate it to Visual Studio 2005's help. I actually succeeded doing it, so I can see the help content in VS's help, but the problem is that filtering doesn't work. In order to filter my content from the other stuff I need to define a filter and assosiate it with a filter query which runs each time the filter is applied. The filter query is a query on the basis of some attribute(s) applied to some topics (in my case all the topics in the collection). Microsoft recommends to use DocSet attribute for this purpose.

Is it possible to apply DocSet attribute to the resulting HxS compiled help unit? Can it be applied to all the topics in the collection?
Coordinator
Mar 20, 2007 at 4:39 PM
This requires modifying the transformations supplied with Sandcastle probably to support a new tag or option and is beyond the scope of the help file builder. You should post your request in the MSDN Documentation Forum requesting that support for this be added.

Eric
Apr 3, 2007 at 7:10 AM
Edited Apr 3, 2007 at 7:10 AM
It might interest people to know that there is (somewhat of) a workaround for this. I found it here: http://blog.opennetcf.org/ncowburn/2007/03/07/SandcastleDocSetFiltering.aspx

Quoting:

Sandcastle uses a series of XML transformations to turn your XML documentation generated by Visual Studio into something that can be integrated with the Visual Studio Help system. The XSL file responsible for setting the various metadata attributes is called utilities_metadata.xsl and can be found in %ProgramFiles%\Sandcastle\Presentation\vs2005\Transforms.

To get Sandcastle to correctly add the DocSet attributes to each help topic, I had to add the following lines just below the <xml> node in the insertMetadata template:

<MSHelp:Attr Name="DocSet" Value="OpenNETCF.SDF2" />
<MSHelp:Attr Name="DocSet" Value="NETFramework" />
<MSHelp:Attr Name="DocSet" Value="NETCompactFramework" />

If you are thinking that I'm hardcoding these attributes and that they will appear in each help topic I ever generate with Sandcastle, you are correct. I will need to modify the OpenNETCF.SDF2 DocSet attribute for each product that I generate help documentation for.
Apr 4, 2007 at 5:17 PM
Wouldn't it be possible to use a custom component to add the DocSet to all the output pages?
i.e. similar to the way the post-transform component works?
Coordinator
Apr 4, 2007 at 8:07 PM
Edited Apr 4, 2007 at 8:08 PM
It's probably possible. I don't know enough about HTML Help 2.0 and its attributes right now to tackle it though. The current attributes are added via the standard transformations.

Eric
Jul 20, 2007 at 4:24 AM
I've just tried the workaround suggested above by BorisS. It did not work for me. I don't know why. Boris's instructions seem very clear. Or is there an extra step I need to do?
Aug 29, 2007 at 8:36 PM
Edited Aug 29, 2007 at 8:41 PM
In the same file utilities_metadata.xsl, there is a line
<xsl:if test="count(/document/reference/versions/versions[@name='netcfw']/version) &gt; 0">
change it to
<xsl:if test="count(/document/reference/versions/versions[@name='netcfw']/version) &gt;= 0">
i.e. add one "=" character at appropriate place.
After that lines below would work and docset attribute would be set.
Now, to customize the value of DocSet, in
C:\Program Files\Sandcastle\Presentation\vs2005\Content\shared_content.xml
change
<item id="netcfDocSetAttribute">NetCompactFramework</item>
to
<item id="netcfDocSetAttribute">Custom Value</item>.
Now your docset would be custom value.
If you are user of DocProject, your docset is not hard-coded, unlike BorisS Solution, you can change the value of netcfDocSetAttribute in the GUI to match your DocSet.
I dont know why, but SHFB doesn't provide many options unlike DocProject. However, it works better than DocProject for me.
Coordinator
Aug 29, 2007 at 8:53 PM
I think DocProject locks you into one presentation style and makes a copy of the presentation style files hence it is able to modify them at will. I chose not to do this so as to make it easy to change styles at will. Also, it doesn't require recreating or updating the project with each new CTP to reflect the changes made to the stock transformations and related files.

Eric
Aug 29, 2007 at 10:34 PM
You are right about DocProject. But I think, the best would be the blend of Both. Instead of Copying files like DocProject and locking to one style, you can simple ask user to set variables in SHFB project. Now, when user presses build, SHFB can copy files, modify required variables and then build the HxS file, cleanup copied files. Those variable are meant to be modified. Otherwise, why they are variables ?
Yes, unlike DocProject, then you won't be able to change XSL at project level. But then, at least, DocSet problem is solved at project level!
Aug 30, 2007 at 3:11 AM
I've just tried the steps suggested above by vkhaitan (in addition to what Boris suggested). It still does not work for me.
Aug 30, 2007 at 6:52 AM
First of all <xsl:if test="count(/document/reference/versions/versions[@name='netcfw']/version) &gt; 0">
there are two such lines. Change in the lower one.
Second thing, there are three styles, vs2005,hana,prototype. You need to change in that style, which you are using.
So, you need to change in the correct presentation style.

Then, How did you check that it doesn't work ?
Aug 31, 2007 at 12:56 AM
Thanks for the suggestions, VK. I had already changed the second of the two lines because the first one contains 'netfw' instead of 'netcfw'. However, I had indeed changed files in the vs2005 folder when I had been using the prototype PresentationStyle. So I have rebuilt my project using the vs2005 PresentationStyle. Consequently I have made some progress, but still do not have it completely working.

With the PresentationStyle matching the folder, I have retried Boris's solution and VK's solution and a combination of the two. VK's solution still does not do anything.

However, Boris's solution and the combined solution now do something. In the Visual Studio Combined Help Collection, if I select ".Net Framework" in the Filtered By drop-down list, my project is shown. When I had mistakenly mismatched the PresentationStyle and the folder, my project was only shown when I selected "(unfiltered)" in the Filtered By drop-down list. So this is progress. I don't necessarily want my project to be shown by the .Net Framework filter, but it was a good test. It proves that adding the line

<MSHelp:Attr Name="DocSet" Value="NETFramework" />

caused my project to be shown with the corresponding filter. I could exclude that line in future if I don't want my project to be shown by the corresponding filter. However, what I really wanted was to have an option specifically for my project added to the Filtered By drop-down list. To achieve this, I added the line

<MSHelp:Attr Name="DocSet" Value="Information Management" />

but no corresponding option got added to the Filtered By drop-down list. So, to make Boris's solution work, I still think there is an extra step I am not doing. For example, how does it know to translate the abbreviation "NETFramework" in the DocSet attribute to the full name ".Net Framework" in the Filtered By drop-down list? I expect there is an entry in one of Sandcastle's files to do this. If so, perhaps I need to add a similar line for my project. I'm not sure how this fits in with VK's solution, which so far has not made any difference for me.

Simon
Aug 31, 2007 at 1:05 AM
I should add that there is also no option for ".Net Compact Framework" in the Filtered By drop-down list. Could this have something to do with why VK's solution does not work for me.

Simon
Aug 31, 2007 at 9:57 AM
How do you integrate your HxS with Visual Studio Help Collection? I hope you are using Help Integration Wizard in Visual Studio.
If that is the case, then when you use Help integration wizard, the wizard comes to a point "Set Collection Properties". In that GUI, In Filters, you need to provide Description you want to come in Filters and Query like "DocSet=Information Management" . After this step, when you build and install your documentation, you will find filters at right place, filtering right thing.

Your explanation of the situation suggests, I bet, My solution is already working for you. You just don't know that it has worked! To prove my point, just open up any html page of your documentation in VS2005 Documentation Explorer(in unfiltered mode). Then Right click->View source. Find out "Docset" attribute. You will find that attribute set by <item id="netcfDocSetAttribute">Custom Value</item>. is indeed there.
The only case is that, you do not have filters set in "Filtered by" which you can now do.
Sep 3, 2007 at 3:33 AM
Thanks, VK. You have given me final piece of information I needed. Instead of Visual Studio's Help Integration Wizard, I'm using FAR HTML (http://www.helpware.net/FAR/). However, I was easily able to work out the equivalent in FAR HTML to your instructions. For anyone else who wants to do this with FAR HTML, see the Edit Filters Dialog topic in FAR HTML's Help.

With this additional step, I found that Boris's solution and VK's solution both work. VK's solution is a little more complex that Boris's solution. Also, if I understand correctly, VK's solution is designed to take advantage of a feature of DocProject that is not present in SHFB. So, as I'm using SHFB, I think I will stick with Boris's solution for now.

Simon
Sep 3, 2007 at 10:28 PM
I've noticed a problem with the filtering in the Visual Studio Combined Help Collection. As I explained above, as an experiment I previously added the line

<MSHelp:Attr Name="DocSet" Value="NETFramework" />

to utilities_metadata.xsl. I have since taken that line out and rebuilt my project with SHFB. Yet, my project's topics still get shown in the Visual Studio Combined Help Collection when I select ".Net Framework" in the Filtered By drop-down list. This is true whether I rebuild the project using Boris's solution or VK's solution. The only way I have been able to stop my project's topics getting shown when I select ".Net Framework" is to rebuild my project with SHFB using the original Microsoft-supplied versions of utilities_metadata.xsl and shared_content.xml. But then of course my project's topics also do not get shown when I select my own "Information Management" custom filter.

I would appreciate it if anyone can suggest what I should do to stop my project's topics getting shown when I select the ".Net Framework" filter.

Simon
Oct 29, 2007 at 2:43 PM
Edited Oct 29, 2007 at 10:35 PM
Hi Guys,

Your explanations are difficult to follow. Can you summarize the steps to add an extry in the filter menu?

Thanks,

Alberto
Oct 30, 2007 at 10:01 AM
Edited Oct 30, 2007 at 10:03 AM


devdept wrote:
Hi Guys,

Your explanations are difficult to follow. Can you summarize the steps to add an extry in the filter menu?

Thanks,

Alberto


Hello,
for adding custom meta attributes (like DocSet) into help files, You can try MetaAttributeComponent from Sandcastle Extensions. This component is also configurable through SHFB GUI.

For adding entry in Help2 viewer filter menu I'm using h2reg utility. There is section in ini file for this task:

[Reg_Filter]
;<nsName>|<FilterName>|<FilterQueryStr>

for example
[Reg_Filter]
My.Registered.Namespace|My Filter Name|"DocSet"="My Library"
Oct 30, 2007 at 10:36 AM
Hi Darilek,


Nice advice, thanks.

If you are using H2REG and SHFB I am sure you can help us also in how to deploy a complete Help2 picking .HxS, .HxC, .HxT, etc. from the SHFB Working folder. Can you please share the steps we need to follow? Eric, the developer behind SHFB is also looking for all the instruction to provide a more Help2 compatible build output.

Thanks.

Alberto
Oct 30, 2007 at 11:54 AM


devdept wrote:
Hi Darilek,


Nice advice, thanks.

If you are using H2REG and SHFB I am sure you can help us also in how to deploy a complete Help2 picking .HxS, .HxC, .HxT, etc. from the SHFB Working folder. Can you please share the steps we need to follow? Eric, the developer behind SHFB is also looking for all the instruction to provide a more Help2 compatible build output.

Thanks.

Alberto


Hello,
I think SHFB (nor Sandcastle) does not generate additional files for Help2 registering (HxT etc.). Yes You will find those files in working directory (You must set CleanIntermediates = false in SHFB), but they are used for final Help2 compilation only.

IMHO, Help2 TOC structure and registration may be different for each project, so universal solution does not exists. For my purposes I used Hx* files generated by nDoc on my older project and I used them for creating more complex TOC structure (which contains more items and plugged sub-namespaces).
Oct 30, 2007 at 12:25 PM
Darilek,


You are right, but at first, we all would love to get all the necessary files and one entry in the documentation browser filter. Don't you think?


Thanks again,

Alberto
Oct 30, 2007 at 12:54 PM
Hello Alberto,

You are right.

If Eric does not implement this feature, I will try realize it in Sandcastle Extensions project as next SHFB plugin. This plugin could generate required Hx* and h2reg.ini files from templates.

Cheers

Darilek Martin
Oct 30, 2007 at 3:10 PM
Darilek,


This would be great and make help file registration a piece of cake ;-)
Start thinking about it.


Alberto
Coordinator
Oct 30, 2007 at 4:37 PM
The 1.6.0.1 release copies the project files to the output folder now. They may still need some work. I'll expand on this in a future release once I learn more about what is needed. The new release will be out in a couple of days.

Eric
Nov 6, 2007 at 1:31 PM
Edited Nov 6, 2007 at 1:38 PM
I am not sure if anyone is still struggling with this filtering issue but here is the easiest way I was able to get my MS Help 2.0 collection output from SHFB to register with Visual Studio 2005 integrated help under my own custom filter using H2Reg.exe (summary of resolution(s) described above):

1) Alter the utilities_metadata.xsl file found at %Program Files%\Sandcastle\Presentation\vs2005\transforms.
2) Add these two lines directly under the XML node of the insertMetadata template: (Thanks BorisS!)
<MSHelp:Attr Name="DocSet" Value="OpenNETCF.SDF2" />
<MSHelp:Attr Name="DocSet" Value="CustomFilterName" />
3) Use SHFB to compile your project as MS Help 2.0 format.
4) Alter your H2Reg.exe command file and add the following line under the Reg-Filter section:
NameSpaceName|Custom Filter Name|("DocSet"="CustomFilterName")
5) Run H2Reg.exe to register your help file collection.

You should see a new filter choice appear in your filter drop down list within Visual Studio help with the name you used for CustomFilterName (H2Reg.exe created this filter list item for you). You should also see your help collection content if you choose your new CustomFilterName in the index view (altering the xls tranform registered your help collection with this filter by adding a DocSet attribute of CustomFilterName to your collection).

Now the only problem I am struggling with is why I cannot see my help content in the Visual Studio 2005 content view. I do not believe this is a filtering issue as my help collection does not appear in the content view regardless of filter choice.

Has anyone managed to get their MS Help 2.0 formatted output of SHFB to appear in the content view of Visual Studio 2005? I didn't have to do anything special to get this to work with NDOC and H2Reg.exe so I am assuming this is a problem with SandCastle?
Nov 6, 2007 at 6:19 PM
dkutin,

I do not want put any advertising on Eric's project :-) You can visit SandcastleExtensions site to see set of build components and SHFB plugins which could solve Your problem (especially MetaAttributeComponent could help You). The upcoming 1.0.3 version will include SHFB plugin for generating Help2 registration files and H2Reg.ini file
Coordinator
Nov 6, 2007 at 7:31 PM
Edited Nov 6, 2007 at 7:32 PM
I don't mind. Looks like you've got some good stuff coming. I think I can cross some stuff off my To Do list :)

I'll add a link to your stuff in the next release's help file too.

Eric
Nov 7, 2007 at 11:21 PM
Hi Darilek,

How do I install the SandcastleExtensions? I have two files a *.DLL and a *.config, where should I copy them?

Thanks,

Alberto
Nov 8, 2007 at 9:00 AM


devdept wrote:
Hi Darilek,

How do I install the SandcastleExtensions? I have two files a *.DLL and a *.config, where should I copy them?

Thanks,

Alberto


Alberto, I'm sorry. I missed instalation notes for 1.0.2 version.
In short: To get MetaAttributeComponent working in SHFB, You must copy component configuration fragment from archive into all *.config templates in {@SHFBFolder}\Templates folder. Component config fragment must placed at the end of component stack but before last component (SaveComponent). Do not forget define the 'id' attribute for this component, to get working it in SHFB UI.

The SandcastleExtensions assembly itself can be placed where do You prefer place it :-) But do not forget specify correct path to assembly in *.config files

I will add detailed instalation notes on SandcastleExtensions homepage
Nov 8, 2007 at 1:21 PM
Thanks Darilek,

I will try an let you know.

Alberto
Coordinator
Nov 8, 2007 at 3:53 PM
Installation will be much easier in the next release of SHFB. I've reworked component support so that it's similar to the plug-ins. You drop the assembly and an XML configuration file that describes it in the .\BuildComponents folder and SHFB takes care of the rest. The configuration file tells it how to merge it into the configuration file at build time.

Eric
Nov 8, 2007 at 5:18 PM


EWoodruff wrote:
Installation will be much easier in the next release of SHFB. I've reworked component support so that it's similar to the plug-ins. You drop the assembly and an XML configuration file that describes it in the .\BuildComponents folder and SHFB takes care of the rest. The configuration file tells it how to merge it into the configuration file at build time.

Eric



Hi Eric, this is very good step. I've only one question: is it possible define component configurator as different class in another assembly (now it is done by static Configure method in component class itself)? This could be useful for configuring default Sandcastle build components for example.
Coordinator
Nov 8, 2007 at 7:26 PM
It's not something I've considered. Most of the stock stuff probably doesn't need modification. If a component lacks a ConfigureMethod, the new release just opens a dialog in which you can edit the raw XML configuration. As such, you can create a component configuration XML file for a stock component, drop it in the build compents folder and you could edit the configuration to override what's in the template config file.

Eric
Nov 9, 2007 at 6:15 AM
Edited Nov 9, 2007 at 6:16 AM


EWoodruff wrote:
It's not something I've considered. Most of the stock stuff probably doesn't need modification. If a component lacks a ConfigureMethod, the new release just opens a dialog in which you can edit the raw XML configuration. As such, you can create a component configuration XML file for a stock component, drop it in the build compents folder and you could edit the configuration to override what's in the template config file.

Eric



Hello Eric, thanks for quick answer. I think this is sufficient solution. I'm looking forward for the new version :-)

Martin Darilek
Nov 13, 2007 at 5:25 PM
Hi All,


I cannot recall the default page when starting the HxS file from Microsoft DExplorer.exe

Looks like there are DefaultPage and HomePage keywords missing inside the file.

Anybody knows why? Or how I define them? My Sitemap already includes a "Set as Default Topic" page.


Thanks,

Alberto
Feb 25, 2008 at 9:55 PM

SimonORorke wrote:
I've noticed a problem with the filtering in the Visual Studio Combined Help Collection. As I explained above, as an experiment I previously added the line

<MSHelp:Attr Name="DocSet" Value="NETFramework" />

to utilities_metadata.xsl. I have since taken that line out and rebuilt my project with SHFB. Yet, my project's topics still get shown in the Visual Studio Combined Help Collection when I select ".Net Framework" in the Filtered By drop-down list. This is true whether I rebuild the project using Boris's solution or VK's solution. The only way I have been able to stop my project's topics getting shown when I select ".Net Framework" is to rebuild my project with SHFB using the original Microsoft-supplied versions of utilities_metadata.xsl and shared_content.xml. But then of course my project's topics also do not get shown when I select my own "Information Management" custom filter.


The help collection got removed from the .Net Framework filter when I used FAR HTML's H2 Collection Wizard to create the collection file (*.HxC) again from scratch and register it. The relevant part of the procedure would have been the automatic unregistering of the filters previously registered for the collection.