Create several TOC nodes for MSHelpViewer (mshc) documentation

Topics: User Forum
Mar 14, 2011 at 5:44 AM
Edited Mar 14, 2011 at 7:02 AM

Hi,

We are working to create a help document for MS HelpViewer (.mshc)  using Sandcastle Help file builder. We have two assemblies like Assembly1.xxx.dll and Assembly2.xxx.dll, and we have created two projects named SandcastleProject1 and SandcastleProject2.

After compiling the Sandcastle project we got an output (mshc) files like Documentaion1.mshc and Documentaion2.mshc.

We included the two .mshc files into single .msha file like Helpcontentsetup.msha in following format..

<div class="package-list">

        <div class="package">

            <!-- NOTE: The "name" span value cannot contain any periods! -->

            <span class="name">Documentation1</span>

            <a class="current-link" href=" Documentation1.mshc "> Documentation1.mshc </a>

        </div>

        <div class="package">

            <!-- NOTE: The "name" span value cannot contain any periods! -->

            <span class="name"> Documentation2 </span>

            <a class="current-link" href=" Documentation2.mshc "> Documentation2.mshc </a>

        </div>

</div>

While view the registered help contents in Help viewer we got the following tree structure in TOC.

             > Class Reference

                         ->   Generated class reference for Assembly1

                         ->   Generated class reference for Assembly2

But our requirement is we need to create one several node inside the registered help contents. Please look the below structure

             > Class Reference

                         ->   Assembly1(need to create)

                                         ->   Generated class reference for Assembly1

                         ->   Assembly2(need to create)

                                         ->   Generated class reference for Assembly2

Could you please suggest your solution for achieving our requirements?

 Thanks,

Vinoth

Coordinator
Mar 14, 2011 at 6:35 PM

See the SHFB help topic on content placement options.  It's possible that you may need to set one project up with the root node and the necessary topic to act as a parent for the Assembly 2 root node and then set up the second project so that it it parented to that topic's ID.  Using the settings in the content layout file, you can specify the topic under which the API topics appear in the main project.

Eric

 

Mar 15, 2011 at 12:37 PM
Edited Mar 15, 2011 at 12:39 PM

Hi Eric,

 Thanks for reply. I read the SHFB help topic and it is really useful, It is working But I have faced another difficulty when I created the nodes using content layout file in the following format.

For mshc1

              >Class Reference

                 ->First Node

Here I am associating standard template files with First Node  to avoid the error (Error BE0055). Then I am assign API reference to First Node.

 And I am giving root node property true and set root name is like Child node1.

I added .msha file(for this .mshc file) alone  into help lib manager. I get the following output in TOC like

MSHC output 1:

                  >Class Reference

                     -> First Node

                         -->Child node1

                             -->Generated Class Reference for Assembly1

 In the Same way I created another .MSHC file. Now  I get the output like     

MSHC output 2:

                >Class Reference

                      ->Second Node

                          -->Child node2

                                 --->Generated Class Reference for Assembly2

Now I merge added the two MSHC files into a single MSHA file, and finally I got the Following TOC structure in Help viewer.

                  >Class Reference

                     ->First Node

                         -->Child node1

                             --->Generated Class Reference for Assembly1

                             --->Generated Class Reference for Assembly2

                   >Class Reference

                      ->Second Node

                          -->Child node2

                             --->Generated Class Reference for Assembly1

                             --->Generated Class Reference for Assembly2

But our requirement is to merge the TOC in following structure.

                >Class Reference

                     ->First Node

                         -->Child node1

                             --->Generated Class Reference for Assembly1

                     ->Second Node

                          -->Child node2

                             --->Generated Class Reference for Assembly2    

 Could you Suggest any solution for my problem?

 

Thanks,

Vinoth

Coordinator
Mar 15, 2011 at 8:37 PM

Add the Second Node topic and any of its child MAML topics to the first project's conceptual content layout file.  Remove the conceptual content from the second project and set its TocParentId property to the ID of the Second Node topic from the first project which is where you want the API content from the second project to appear.  When you install the help files, it should now use the first project's Second Node topic as the parent for the API content from the second project.

Eric

 

Mar 16, 2011 at 11:16 AM

Hi Eric,

Thanks for the answer. It is working .But Still it's having the problem in another format. Now I Created the nodes using content layout file in the following format.

For mshc1

        >Class Reference

                   ->First Node

                    ->Second Node

Here I am associating standard template files with First and second nodes. Then I am assign API reference to First Node. And I am giving root node property true and set root name is like Child node1.

For mshc2

Here I am giving root node property true and set root name is like Child node2. And assign Second node ID to TocparentID.

Now I merge added the two MSHC files into a single MSHA file, and finally I got the Following TOC structure in Help viewer.

             >Class Reference

                   ->First Node

                          -->Child node1

                            --->Generated Class Reference for Assembly1

                              --->Generated Class Reference for Assembly2

                    ->Second Node

                          -->Child node2

                               --->Generated Class Reference for Assembly1

                               --->Generated Class Reference for Assembly2

But our requirement is like....

               >Class Reference

                      ->First Node

                           -->Child node1

                             --->Generated Class Reference for Assembly1

                      ->Second Node

                            -->Child node2

                               --->Generated Class Reference for Assembly2

Could you suggest any solution for my problem?

Thanks,

Vinoth

Coordinator
Mar 16, 2011 at 8:33 PM

Since it's duplicating the topics under both child nodes, it looks like you've perhaps got both assemblies in both SHFB projects.  Put one assembly in one project and the other in the second project.  That should solve the issue.

Eric

 

Mar 17, 2011 at 9:52 AM

Hi Eric,

         Thanks for the answer.

          I am using one assembly for  one Project and another assembly for another Project. But I got the same Problem again.

   Please suggest any solution for my problem?

Thanks,

Vinoth

Coordinator
Mar 17, 2011 at 8:25 PM

I'm not sure what else to tell you.  If you can duplicate the problem in a small example that you can send me, I'll take a look at it.  My e-mail address is in the About box in the GUI and in the footer of the pages in the help file.

Eric

 

Mar 25, 2011 at 9:43 AM

 

Hi Eric,

         Thanks for reply.

       I sent my sample project to your mail Id on  3/22/2011.In the subject line I put this discussion heading.

    Please Could you suggest solution for this requirements ?

Thanks,

Vinoth

Coordinator
Mar 25, 2011 at 3:55 PM

I haven't had time to look at it yet.  I'll let you know what I find when I do.

Eric

 

Mar 28, 2011 at 9:51 AM
Edited Mar 28, 2011 at 9:52 AM

Hi Eric,

   Thanks for the reply. Sorry I forget to tell you something. I have used following assemblies.

           1)  Assembly1.dll

           2)  Assembly2.dll

 I have created the nodes using content layout file in the following format.

For mshc1

       >Class Reference

                  ->First Node

                   ->Second Node

I associated standard template files with First and second nodes. Then I assigned API reference to First Node and I set root node property to be true and root name to Child node1.Here I used Assembly1.

For mshc2

I set root node property to be true and root name to Child node2. Then I assigned Second Node ID to TocparentID. Here I used Assembly2.

When I add mshc2 file into msha1 file, the TOC structure in Help viewer the content is merged in the following manner.

             >Class Reference

                   ->First Node

                         -->Child node1

                           --->Generated Class Reference for Assembly1

                             --->Generated Class Reference for Assembly2

                   ->Second Node

                         -->Child node2

                               --->Generated Class Reference for Assembly1

                               --->Generated Class Reference for Assembly2

When I click the Child node2 (or its content) in TOC, Child node1(or its content) shows by default in the output Document.

Our requirement is as follows

               >Class Reference

                     ->First Node

                           -->Child node1

                            --->Generated Class Reference for Assembly1

                     ->Second Node

                           -->Child node2

                               --->Generated Class Reference for Assembly2

Could you please suggest your solution for achieving this requirement?

Thanks,

Vinoth.M

Coordinator
Mar 28, 2011 at 8:27 PM

I was able to duplicate the problem and I have identified the cause. The problem is the use of the RootNamespace container property. When Sandcastle generates the root namespace page, it always assigns it the ID “R:Project”. When you have two MS Help Viewer files with root namespace pages parented to another topic, this violates the unique ID rule and thus it merges the content and children of all the pages with that ID in both parent topics. The only workaround for now is to turn off the RootNamespaceContainer property in one or both projects. You could simulate a root namespace container with a MAML topic containing links to each namespace if needed.

I’ll open a work item and see if there’s a way to correct the issue at some point during the build. I’m not sure of the best way to fix it yet since I think the Sandcastle XSL transformations or content files have some dependency on the “R:Project” ID value as a link target. I’ll look into it when I get a chance.

Eric

 

Coordinator
Mar 28, 2011 at 8:44 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.