Getting the results /in to/ MSDN

Topics: General Questions, Help 1.x/2.x
Dec 11, 2007 at 1:30 PM
I keep reading that it is/should be possible to take the results of running DocProject and get them in to MSDN (I'm running VS2K5, if it makes any difference) using the FAR tools.

The problem is that I can only find examples of using the FAR tools starting with the output from something other than DocProject. I thought that the process should be the same, but nothing I've tried works.

If you have experience of doing this and would like to share, by private mail if TPTB here object to a slightly off-topic thread then please (PLEASE!!!) either let me know here or mail me at sejhemming-at-gmail-doc-com.
Dec 11, 2007 at 3:50 PM
Just so you know what's occurring...

I'm generating my .HxS file then firing up FAR.

I go to the "H2 collection Wizard" and create a new .HxC file, point it at my .HxS file, allow it to create all of the other files it needs and let it generate the .ini file. If I register the collection using the FAR tool it works and the H2 File viewer can see the namespace.

If I try and merge the collection with the ms.vsipcc+ namespace (which I'm given to understand I should as I'm using VS2K5) using the command H2Reg.exe -R -M "cmdfile=H2Reg_cmd.ini", it tells me that it's merging. At the end of the process I open the MSDN library and don't get a warning that new items are being added to the collection and the help for my namespace isn't there.

Now, is this a problem with something I'm doing or is there a fundamental difference with the output that DocProject produces that prevents this process from working?

--
Stuart
Coordinator
Dec 11, 2007 at 4:10 PM
Edited Dec 11, 2007 at 5:15 PM
EDIT: Fixed BPC Link (1:14 PM)

Hi,


I keep reading that it is/should be possible to take the results of running DocProject and get them in to MSDN (I'm running VS2K5, if it makes any difference) using the FAR tools.

I was able to successfully integrate DocProject's Help 2.x output into Visual Studio 2005's help collections (viewable in Document Explorer) using the Help Integration Wizard. The only file required as input is the .HxS file that DocProject generates. In a DocProject you'll find it in the project's {config}\bin folder and in a DocSite you'll find it in the Help\bin folder; the folders are hidden in Solution Explorer.


The problem is that I can only find examples of using the FAR tools starting with the output from something other than DocProject. I thought that the process should be the same, but nothing I've tried works.

I have not tried FAR's tools. Have you specifically tried H2Reg?

H2Reg and FAR in general may require Collection-level files, which use the same extensions as the Help 2.x project-related files although they are different. Neither Sandcastle nor DocProject generate these types of files; however, there is a Sandcastle Help File Builder plug-in provided by the Sandcastle Extensions project here on CodePlex that will generate them for you. It's open source, so you may want to view the source code and add the appropriate steps to your project's Build Process Component if in fact you need collection-level Help 2.x files. In the future I plan to add the ability for DocProject to generate collection-level files automatically when Help 2.x output is enabled, with a project option to enable/disable the feature.

If collection-level Help 2.x files aren't required by FAR then please describe the result you are getting in more detail. Are there any errors? Is your help simply not appearing in Document Explorer?

- Dave
Coordinator
Dec 11, 2007 at 4:17 PM
Hi,

We began to reply at the same time :)

I'm not really that familiar with Help 2.x so I don't know for sure if there is a difference, but I don't think so. DocProject uses the Help 2.x compiler service to build the .HxS file. I don't think there's anything more that can be done in DocProject (other than generating collection-level files automatically, but it seems that you're able to have FAR do that for you?).

My suggestion is to post this question in the Developer Documentation and Help System forum. You may get a better response from someone more knowledgeable about Help 2.x. If you choose to post I'll monitor the thread as well.

- Dave
Dec 12, 2007 at 8:00 AM
I'm clearly just too stupid to be able to cope mentally with what's going on here.

I have bowed to pressure and tried using the Help Integration Wizard. Now this is where my understanding fails. Yes I created the project and yes it created an installer and yes it seemed to install.

But.

I can call up my MSDN library one of 2 ways, by pressing F1 in VS or by selecting Programs|Microsoft Developer Network|MSDN Library for Visual Studio 2005.

If I do the former my collection shows, if I do the later it doesn't so there is obviously something different about these collections but, as I've suggested I'm too dumb to know just what that might be.

I'm going to post something in the Developer Documentation and help System forum, as suggested once my head stops bleeding after all the banging against the wall 8-).


Coordinator
Dec 12, 2007 at 9:02 AM
Hi Stuart,

I'm pretty much in the "dumb" club with you when it comes to Help 2.x :)

I find it strange though that you can get the collection to work with the Help Integration Wizard, but not H2Reg. I guess H2Reg does require something to be different after all. Hopefully you'll get some answers in the MSDN forums.

- Dave
Dec 12, 2007 at 9:59 AM

I'm pretty much in the "dumb" club with you when it comes to Help 2.x :)

8-)


I find it strange though that you can get the collection to work with the Help Integration Wizard, but not H2Reg. I guess H2Reg does require something to be different after all. Hopefully you'll get some answers in the MSDN forums.

Yeah, I've got that desperate that I've done the unspeakable and cross-posted it to a couple of Help-related yahoo groups too.
Coordinator
Dec 12, 2007 at 11:02 AM
That's fine, IMO, the answers may help a lot of people. Help 2.x seems to be a confusing topic for some. To be honest, I've read about several aspects, a few different times, and I'm still somewhat confused. Although I'm not really confused about its design, just why it appears to be so difficult to use - lots of bugs it seems.

Gather what information you can in the forums (I'll try to help if I can) and then I'll compile the information into a How To article here mixed with information from other sources (e.g., see Sandcastle Help for some links to articles). You'll get credit too in the article, of course :)

The goal will be to write a How To topic that should work for most people to get Sandcastle's Help 2.x output integrated into the Visual Studio help system with minimal effort. I'm certainly not against recommending H2Reg if it's actually the best choice, although since DocProject is integrated into Visual Studio, the Help Integration Wizard may be more suitable in most cases.

- Dave
Dec 12, 2007 at 12:26 PM
I'm getting somewhere, but it's slow going.
Dec 12, 2007 at 2:19 PM
OK.

As I've suggested, I've got my collection into the VS Help collection.

Point is, the top level entry is "namespaces" under which is my namespace's top-level object.

Can I do anything so that I can change this so that my namespace top-level object is at the top?

If I can't, what happens when I try and add another?
Dec 12, 2007 at 2:34 PM
I'd really like the 'NameSpaces' entry to go away, but if you can't do that then I've a kind of a workaround in that in FAR I tell the system I want a hierarchical TOC and put a dummy entry at the top so that I have, say the company name as the top-level TOC entry, under that is "NameSpaces" and under that is the list of actual enttries that I want.

--
Stuart
Dec 12, 2007 at 3:34 PM
I really should look more closely, the above doesn't work as I thought it would.

Instead of ending up with ...

- QubeControls
-- Namespaces
--- QubeControls.Common
--- QubeControls.Data

I got

- QubeControls
-- Namespaces
--- QubeControls.Common
- QubeControls
-- Namespaces
--- QubeControls.Data


8-(

--
Stuart
Coordinator
Dec 12, 2007 at 4:33 PM
Hi Stuart,

I think you can set the Namespaces topic that is produced by Sandcastle to be the top element in the Help Integration Wizard, but I'm not absolutely sure. In the How To article on MSDN, try to skip steps 8 and 10, and apply steps 11 through 13 to the original Namespaces topic instead of the New Node (which you didn't create this time around). I really have no idea if that will work - it's just a guess.

- Dave
Coordinator
Dec 12, 2007 at 4:35 PM
Edited Dec 12, 2007 at 6:12 PM
EDIT: negated the subject :)

I forgot to mention in my last post that I may be able to add an option to have Sandcastle not generate a top-level node. I'll give it a shot for the next release.
Coordinator
Dec 12, 2007 at 4:37 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.
Dec 13, 2007 at 8:51 AM

davedev wrote:
I think you can set the Namespaces topic that is produced by Sandcastle to be the top element in the Help Integration Wizard, but I'm not absolutely sure.

Yeah, Got that to work. instead of using the RProject.htm file as the top-level node I used the Nblah.htm file.

Of course, I realised that this is not going to work if the project you're documenting spans more than 1 namespace.

You know, somethimes I get frightened by just how stupid I am!

--
Stuart
Coordinator
Dec 13, 2007 at 10:20 AM
Nah, don't be so hard on yourself :)