Sandcastle and H2Reg

Topics: Developer Forum, User Forum
Jul 25, 2007 at 3:35 PM
Hi,

To cut the long story short (if somebody recognizes it), issues we have are:
a) Why Sandcastle generated HTML 2.X files, when registered with H2Reg tool, don't show in VS help "Contents" tab and "Index" tab with "Visual C#" filter applied?
b) Why Sandcastle by default generates only one HxS file? Is that enough and how are we supposed to integrate that with VS help system?

And now the entire story:

Previously we used NDoc to build HTML 2.X files for VS.NET help system. NDoc produced a number of files (.HxS, .HxC, .HxT etc.). Then we used H2Reg tool in our MSI setup to register that files to VS.NET help system on target machines (we sell components, our customers have hundreds of installations).
Since NDoc project stopped to exists we can't build help files that target .NET Framework 2.0. Therefore we started using SandCastle (June 2007 CTP) and Sandcastle Help File Builder (http://www.codeplex.com/SHFB). It works for HTML 1.X files (CHM).

However, when we use Sandcastle to build HTML 2.X files we got only one .HxS file! H2Reg requires more files in order to complete help registration. I have set Sandcastle Help File Builder CleanIntermediates option to false, and was able to find required files in temporary "Working" folder.

But, when H2Reg is executed with that input files during our product setup, resulting VS help system has few issues:
a) "GemBox.Spreadsheet " namespace NEVER appears in help "Contents" tab.
b) Our classes are listed in "Index" tab only if filter is set to "GemBox.Spreadsheet" or "no filter", when filter is set to some language "Visual C#" our classed are not in the index.
Previously (when we used NDoc to build HTML 2.X files) none of the issues appeared. Our namespace was present in "Contents" tab and our classed were indexed even with "Visual C#" filter. Any clue why this issues are happening?

Regards,

Zeljko
GemBox Software
Aug 19, 2007 at 12:19 AM
I had the same, and after several hours of tedious work, realised that the problem occurs when the HxS file contains 2 dots - in my case DicomObjects.NET.HxS. If I use a different name (controlled in my case by the HtmlHelpName in SandCastleBuilder) then all is well.

I will report this as an issue.

Dave Harvey
Aug 28, 2007 at 5:00 PM
Edited Aug 28, 2007 at 5:01 PM
The reason the filters don't show up is because the generated help topics lack an "XML data island" that declares the DocSet filters that the topics match.

Take a look at http://www.codeplex.com/SHFB/Thread/View.aspx?ThreadId=12806 and http://www.codeplex.com/SHFB/Thread/View.aspx?ThreadId=8374
Oct 28, 2007 at 11:00 PM
Edited Oct 28, 2007 at 11:01 PM
ZeljkoS,


Did you discover why (.HxS, .HxC, .HxT etc.) were not generated?

We see those files in the Working dir too but shouldn't they have the same name of thr HxS? Did you succeed simply renaming them? Is it possible that to get those files you need to pick them from a temp folder?


Thanks,

Alberto
Coordinator
Oct 29, 2007 at 12:26 AM
The help file builder never copied them to the output folder. I'm not very familiar with Help 2 so I wasn't aware that they were needed. The upcoming 1.6.0.1 release will copy the files to the output folder. They'll still need modification to be useable (i.e. deleting the DOCTYPE and compiler options, etc). When I get enough time I'll take a look at extending the support for this so it does that automatically and perhaps add other stuff that may be useful in generating an installer.

Eric
Oct 29, 2007 at 1:40 PM
Hi Eric,

Thanks for your prompt answer. Please, rename them as the help file name too and give a look to http://www.helpware.net/mshelp2/h2tutorial.htm for the implementation details (I don't think that you need to modify them a lot).

I look forward to be able to have our full help system build by your SHFB !

Thanks,

Alberto
Coordinator
Oct 29, 2007 at 6:00 PM
It uses the same name as the help file for the project files. Thanks for the link. I'll check it out and add it to the notes for the future revisions.

Eric
Nov 5, 2007 at 3:33 PM
ZeljkoS -

Just wondering if you ever reached a resolution for this issue as I am experiencing the exact same problem. I am able to compile Help 2.0 formatted output using the SHFB utility - Thanks Eric! - but when I use H2Reg.exe to register the collections with Visual Studio 2005 I do not see my help collection in the contents view regardless of the filter. I do see my help collection in the index view when the filter is set properly (no filter or my custom filter). I have read multiple threads related to creating new filters using FAR or the Help Integration Wizard and setting the DocSet property to get my help collection to appear in various filters by modifying the xls transform utilities_metadata.xls, but it appears to only affect the index view and not the contents view as I am still unable to view my help collection in the contents view regardless of the filter.

Has anyone gotten any further regarding the contents view?

Thanks!
Nov 6, 2007 at 8:21 AM
Hi,

We were unable to solve problems listed in my first post. Therefore few months ago we reverted back to NDoc. We just copied our VS 2005 solution to VS2003 solution and used it as input for NDoc for .NET Framework 1.1.
I hope Sandcastle will be mature in few months time, so we can use it to build help for our next release.

Regards,

Zeljko