Help collection integration  
Author Message
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi All,

This is for plugging in one help collection to another one, Let me explain the requirement:

We have two VSIP packages, say Product-1 and Product-2, and both have their on help collections.

Let the root node in TOC of the first collection be HelpProduct-1 and the second- HelpProduct--2.

These packages will be installed in separately, and the requirement is to show in help contents, these two collections as children of a common rootnode, say, 'MyCompanyProducts'.

So if I install product-1 first, the help contents should display-

MyCompanyProducts
     HelpProduct-1
         node-1
         node-2
 

Then, when Product-2 is installed, the contents should display like-

MyCompanyProducts
     HelpProduct-1
         node-1
         node-2
     HelpProduct-2
         node-1
         node-2
 

That is, the help collection from product-2 should be added as child node of the common root node.

This should happen similarly if product-1 is installed after product-2.

Any idea how to achieve this, I am using VS setup project and integration is done using the msm file.

Thanks,

Sajith



Visual Studio19  
 
 
Frank M. Palinkas





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi sajithpt,

The key to accomplishing what you want is controlled in the Visual Studio "Help Integration Wizard 2005 (Page 3 of 4) Build the TOC" dialog box, and consists of creating a Parent node with your .HxS collections set as Child nodes.

In order to create a "combined help collection" consisting of 2 or more .HxS files, and have them listed successfully with a Parent node and subsequent Child nodes in the VS 2005 Help Contents Window, please follow these steps:

1. Open VS 2005 and then open the Help Integration Wizard 2005 from the File > New Project > Help Integration Wizard.
- Enter the title of your combined help collection in the "Name" field.
- Make sure the "Create Directory for Solution" checkbox is checked.
- Click the "OK" button.

2. In the "Help Integration Wizard (Page 1 of 4)" dialog box:
- Choose the "Setup Project" radio button.
- In the "Target" dropdown list, choose "Visual Studio 2005".
- Click the "Next" button.

3. In the "Help Integration Wizard (Page 2 of 4)" dialog box:
- Click the "Add" button.
- Navigate to the folder which contains your .HxS files.
- Select ALL of the .HxS files using the Shift key. The order of these files is not important now.....we'll fix that in the next step.
- Click the "Open" button. This adds all of the .HxS files to the "Source Files" window.
- Click the "Next" button.

4. In the "Help Integration Wizard (Page 3 of 4)" dialog box:
- Keep the "Plug-in Style" radio button selection set to "Hierarchical".
- Click the red book icon in the "Help Collection TOC" window on the left, and enter a title for your combined help collection. This will become the Parent node of your combined collection.
- In the "Exclude from TOC" window on the right, select the title of your 1st Child node to appear under the Parent node.
- Click the "Include" button.
- Do the same for each title appearing in the Exclude from TOC window, setting the order of precedence in which they will appear under the Parent node.
- Click on the "Plug-in Node Properties" icon.
- Edit the name which shows in the text box, eliminating all spaces between words in the name. Use underscores or another naming convention.
- Click the "Next" button.

5. In the "Help Integration Wizard (Page 4 of 4)" dialog box:
- Enter a namespace for your combined help collection. Make sure there are no spaces between words in the namespace.
- Click the "Finish" button. This will return you to the VS 2005 IDE, and your pre-builds for the combined help collection will be showing in the Solution Explorer window.

6. In the Visual Studio 2005 "Solution Explorer" window:
- Right-click the MergeModule pre-build solution.
- Click "Build" in the menu.
- Verify that the MergeModule build has finished successfully
- Right-click the .MSI/Setup.exe pre-build solution.
- Click "Build" in the menu.
- Verify that the .MSI/Setuo.exe build has finished successfully.
- Save the builds.
- Close Visual Studio 2005.

7. Go to your folder containing the .HxS files, which now contains the combined help collection folder created by the Visual Studio build process.
- Open the new combined help collection folder.
- Open the .MSI/Setup.exe folder.
- Open the Debug folder.
- Double-click on the Setup.exe package, or right click on the .MSI package and choose Install in the menu.
- Follow the Install wizard process.
- After successfully completing the Install procedure, close all folders.

8. Open Visual Studio 2005 and click on the Help Contents tab to open it.
- Your combined help collection will be listed in the Help contents window navigation tree. Expand the Parent node and you will see your Child nodes listed in the order of precedence you set in the Help Integration Wizard procedure.

Hope this helps,

Frank M. Palinkas
MCP, MCT, MCSE, MCDBA, A+
Senior Technical Communicator and Web Accessibility Designer



 
 
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi Frank,

Thank you very much for the reply.

The way you have described works for installing two different HXS files in single install. But in my case, there are two HXS files and each of these has to be installed by different installation programs and has to produce the same result.

I have to use two different installation programs, one for each HXS file because, these are help collections for two different products and these will be insatlled as part of these product install.

Say, after install of the first product, help contents should display-

MyCompanyProducts
     HelpProduct-1
         node-1
         node-2
 

and after install of second product, the contents should display-

MyCompanyProducts
     HelpProduct-1
         node-1
         node-2
     HelpProduct-2
         node-1
         node-2
 

The products may be installed in the different order, it should not affect the TOC. Here, 'MyCompanyProducts' is the parent node for the combined collection.

Also it should be possible to remove any one or both collections from the VSCC, and it should be possible to uninstall any one or both of these help collections altogether. So this doesn't permit me to go for the approach you have described and have a single install for both the help collections.

Any idea on how to do this Any pointers or suggestions on how to proceed will be really helpfull.

Thanks,

Sajith


 
 
Frank M. Palinkas





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi Sajith,

My apologies, now I see your point.

Knowing that creating either a standalone or combined Help2 Collection is a bona-fide Windows Desktop application (.exe) in itself, can this .exe can be "adjusted" or "added to" after the fact

Is there is a way to auto-add a new Child node Help2 Collection to the Parent node by means of a silent install by the mother application Personally, I've never seen this done before, and doubt very much if it's possible. However, I sure don't know everything!

Maybe one of the Microsoft team can add to this.

In any case, I hope the earlier instructions I posted may one day be of use to you or anyone else reading this.

Kind regards,

Frank



 
 
Frank M. Palinkas





PostPosted: Developer Documentation and Help System, Help collection integration Top

Just thinking....

Instead of using the Help Contents window to show your Child node Help 2 Collections under one Parent, it might be possible to use the Dynamic Help window to accomplish this, and add individual H2 Collections to a Parent node on an intermittent basis there. Please take a look at the Dynamic Help window documentation and see if its possible.

Frank



 
 
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi Frank,

From the dynamic help window description, it doesn't seem to be possible. Can you please elaborate on this, to me the contents window and dynamic help window seem to be completely different.

The step by step description on preparing "combined help collection" would be helpful to anybody who reads, I really appreciate this.

Thanks,

Sajith


 
 
Frank M. Palinkas





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi Sajith,

You're most welcome!!

Once again, I don't know if this will work regarding the installation method you require.

I haven't included Help in the Dynamic Help window since early 2003, but if I remember correctly, in this case we're not dealing with .HxS files. We need the uncompiled format of a .chm, or simply said a web-based help module. I don't know if it can be auto-installed as a plugin to the Dynamic Help window, based on instructions given by the install procedure of a mother program. The last time I did it was as an experiment, manually following the instructions in the Dynamic Help documentation.

If you think it's worth pursuing, then start experimenting following the Dynamic Help documentation. I wish I could tell you more, but that's the limit of my knowledge and experience with it at this point.

Kind regards,

Frank



 
 
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi All,

Just wanted to keep this thread alive...

The problem is not solved yet.

It will be very helpful if anybody from microsoft can confirm whether this is possilble or not.

Thanks a lot...

sajith


 
 
Paul ORear MSFT





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hello Sajith - to do this you'll want to create a container collection for both of your products. We do something similar with Visual Studio documentation. We have the VSCC - Visual Studio Combined Collection that is mostly a shell that other content then plugs into.

In your case, you'd want to create your own 'CC' collection that both of your collections would plug into. Your CC collection would define an .hxt with essentially just the top level node 'My Company Products'. When your products 1 or 2 are installed, they should then plug in to your CC collection which would surface them under your CC's TOC.

So, in the end, you would only plug your CC collection into our VSIPCC collection, and then your other products would plug in to your own CC collection.

The best examples of how to do something like this are to look at the Visual Studio collection files and general architecture. The collection files can be found in the following location:

\Program Files\Common Files\Microsoft Shared\DevHelp

Look primarily at the VSCC and VSIPCC folders.

You can examine the general architecture using the namespace.exe tool that is installed with VSSDK, or a shareware tool like FAR.exe from http://helpware.net



 
 
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi Paul,

Thanks a lot for your reply.

I tried doing this, as you suggested and explained in the following link in visual studio sdk help-

ms-help://MS.VSCC.v80/MS.VSIPCC.v80/MS.VSSDK.v80/dv_vshik_2/html/57e2cc64-78b5-497b-a458-717df8a983d3.htm

But, I am finding the following issue- There are three entries in MSVSCC, one for the parent collection and other two for the child collections.

Initially, if I select all these three collections in VSCC, the TOC shows as expected-

MyCompanyProducts
     HelpProduct-1
         node-1
         node-2
     HelpProduct-2
         node-1
         node-2
 

MyCompanyProducts is from the parent collection, HelpProduct-1 and HelpProduct-2 from the child collections. (The parent collection namespace is plugged into ms.vsipcc.v80, and the child collection namespaces to the parent collection namespace)

Now, if I keep the parent collection unselected and the child collections selected in VSCC, the TOC shows-

HelpProduct-1
    node-1
    node-2
HelpProduct-2
    node-1
    node-2
 

ie. without the parent collection node. At this time, namespace.exe shows the child collections plugged into ms.vsipcc.v80. This happens automatically and so if at this stage if the parent collection is also selected in VSCC, the TOC shows-

HelpProduct-1
    node-1
    node-2
HelpProduct-2
    node-1
    node-2
MyCompanyProducts
    HelpProduct-1
        node-1
        node-2
    HelpProduct-2
        node-1
        node-2

That is child collections are shown at the top level and also as children to the parent collection. (This is because the child name spaces are plugged into both the parent namespace and also to ms.vsipcc.v80.

Any idea how to solve this. Can this be done like there will be only one entry in the VSCC, that is for the parent collection and the child collections are plugged into the parent collection, but these are not displayed as selectable collections in VSCC Or else can we prevent VS from doing an automatic plug in of child namespaces to ms.vsipcc.v80 when only the child collections are selected in VSCC

Thanks a lot..

Sajith


 
 
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hello Paul,

Just wanted to bring this up again. because, I still could not find a solution to this.

It would be of great help if you can have a look,

Thanks,

Sajith


 
 
Paul ORear MSFT





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hello Sajith - my apologies - this went beneath my radar. Are you using Help Integration Wizard to try to accomplish this I'm not sure that Help Integration Wizard will facilitate this kind of setup. Your scenario is more complex than what that was designed for.



 
 
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hellp Paul,

I am not using Help Integration Wizard. Instead, I would be creating a VS setup project directly and add the required merge modules.

Now, I am trying this out creating the .HxS files, the respective collection level files and registering the collections using FAR H2 Utilities.

Thanks,

Sajith


 
 
Paul ORear MSFT





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hi Sajith - If you view the collections in Namespace.exe or the FAR utilities, do you see your child collections plugged into your own parent collection as well as into VSIPCC

For example - you have your own parent, let's say Sajith.Parent and it shows Sajith.Child1 and Sajith.Child2 plugged into it, like:

Sajith.Parent
Plugins
Sajith.Child1
Sajith.Chid2

Do you then see in MS.VSIPCC.v80:

MS.VSIPCC.v80
Plugins
Sajith.Parent
Sajith.Child1
Sajith.Child2

I suspect that is what's going on. You probably just need to remove a couple entries in your HelpPlugin table for your child collections. They should only specify to plug into your own parent collection.



 
 
sajithpt





PostPosted: Developer Documentation and Help System, Help collection integration Top

Hello Paul,

I am not using my own installer and HelpPlugin table now, instead,  I am installing the help using FAR H2 utilities tool directly from the .HxS file (and collection level files).

After installing 'Sajith.Parent', 'Sajith.Child1' and 'Sajith.Child2', initially the names spaces are plugged in correctly-

Sajith.Parent
      Plugins
            Sajith.Child1
            Sajith.Chid2

and MS.VSIPCC.v80-

MS.VSIPCC.v80
     Plugins
           Sajith.Parent

At this stage, the help-contents show up the expected way. But the MSVSCC lists these three collections (there are three entries one each for the parent and child collections with the checkbox to select/unselect)

Now, if we unselect 'Sajith.Parent' in VSCC and close restart VS(keeping child collections selected), the namespaces become-

Sajith.Parent
      Plugins
            Sajith.Child1
            Sajith.Chid2

and

MS.VSIPCC.v80
     Plugins
           Sajith.Parent
           Sajith.Child1
           Sajith.Child2

At this stage, Help -Contents will list 'Sajith.Child1' and 'Sajith.Child2' with out the parent node (Only one set because 'Sajith.Parent' is not selected in VSCC)

Now if we select 'Sajith.Parent' in VSCC again and close restart VS, Help Contents start to show two sets of 'Sajith.Child1' and 'Sajith.Chid2'- One set directly in flat style with out the parent node and the other set under the parent node for 'Sajith.Parent'

Hope the scenario is more clear to you now. Please let me know if you want more info or clarification.

Thanks a lot for all your co-operation and patience.

Thanks,

Sajith