none
Installing two versions of documentation in Help Viewer 2.x

    Question

  • Hello,

    I need to install two concurrent versions of documentation in MS Help Viewer 2.2, for the two versions of our product. Basically, our product comes in versions 8 and 9, which are now almost identical but will evolve diffently. The associated documentation is subdivided into a set of frameworks and toolkits classes, in a tree structure like the following:

    Doc V8
    --Namespace A
    ----Class A1
    ----Class A2
    ...
    --Namespace B
    ----Class B1
    ----Class B2

    Doc V9
    --Namespace A
    ----Class A1
    ----Class A2
    ...
    --Namespace B
    ----Class B1
    ----Class B2

    The .mshc files for V8 and V9 are generated separately with Sandcastle. I've set different TopicVersion and TOCParentTopicVersion values. Basically, both files contain the same classes and the same topics, differing with the version.

    The files install with no problem. The problem is the duplication of the topics: each topic appears twice, one for V8 one for V9, in each tree, whether the topic is a Namespace, class, method, etc..

    Doc V8
    --Namespace A (v8)
    ----Class A1 (v8)
    ----Class A1 (v9)
    ...
    --Namespace A (v9)
    ...

    Doc V9
    --Namespace A (v8)
    ----Class A1 (v8)
    ----Class A1 (v9)
    ...
    --Namespace A (v9)

    I tried playing with the manifest file, using for instance 2 different manifest files, or one manifest file including the 2 packages. Microsoft uses e-tags, but I could not find out if they are appropriate in this case, nor how to generate and use them properly. The metadata island of one of the help topic file is as follows. The corresponding V8 and V9 files have correct TopicVersion and TOCParentTopicVersion values, however they have the same guid values. In Sandcastle, I use hashed member name topic file naming method.

        <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE9" />
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <title>RepPP.Framework.SPA Namespace</title>
        <meta name="Language" content="en-us" />
        <meta name="System.Keywords" content="RepPP.Framework.SPA namespace" />
        <meta name="Microsoft.Help.F1" content="RepPP.Framework.SPA" />
        <meta name="Microsoft.Help.Id" content="N:RepPP.Framework.SPA" />
        <meta name="Microsoft.Help.ContentType" content="Reference" />
        <meta name="BrandingAware" content="true" />
        <meta name="container" content="RepPP.Framework.SPA" />
        <meta name="file" content="3876558D" />
        <meta name="guid" content="3876558D" />
        <meta name="Microsoft.Help.SelfBranded" content="true" />
        <meta name="Microsoft.Help.TopicVersion" content="9" />
        <meta name="Title" content="RepPP.Framework.SPA" />
        <meta name="Microsoft.Help.Keywords" content="RepPP.Framework.SPA namespace" />
        <meta name="Microsoft.Help.F1" content="RepPP.Framework.SPA" />
        <meta name="Microsoft.Help.Category" content="DevLang:CSharp" />
        <meta name="Microsoft.Help.Category" content="DevLang:VB" />
        <meta name="Microsoft.Help.Category" content="DevLang:C++" />
        <meta name="Microsoft.Help.Locale" content="en-us" />
        <meta name="Microsoft.Help.TopicLocale" content="en-us" />
        <meta name="Microsoft.Help.TocParent" content="G:RepPP.Framework" />
        <meta name="Microsoft.Help.TOCParentTopicVersion" content="9" />
        <meta name="Microsoft.Help.TocOrder" content="0" />

    Can anyone help me with this? I'v looked around but info is hard to find. I'm testing it with Help Viewer 2.2 on VS 2015, Windows 10.

    Thanks, Claudette
     
    Friday, September 2, 2016 2:19 PM

All replies

  • More likely than not you're having problems due to using the same naming method in both projects since the API members will generate the same IDs in both projects.  This may not cause problems when the help viewer merges the content but will with the TOC and linking between topics.  You can probably work around this by using different naming methods in each project (GUID for one and Hashed Member Names for the other for example).  Each help project would also have to have a unique title/name.  If you go with this approach, I think you will have to use at least one conceptual topic and make it the parent of the API content.  That will avoid duplicate namespace entries at the root level in the TOC.

    A more workable solution if you don't have to keep the two documentation sets separate is to use the Version Builder plug-in to merge the content from both projects into a single file with a Version Information section in each API topic that shows to which version it applies.  If you do this, you'd put any conceptual content in the primary project that contains the plug-in.  The other project would simply be used to supply the API information for the plug-in.

    Eric

    • Proposed as answer by EWoodruff Friday, September 2, 2016 3:32 PM
    Friday, September 2, 2016 3:32 PM
  • Hi Eric,

    The Version Builder solution is interesting. I read quickly the description in the Sandcastle documentation.

    Can Visual Studio determine which version I'm using and display the topic for that version? Or does it display the most recent version of a topic by default?

    I have another set of documents, again in V8 and V9, but not generated from Sandcastle: home-made using doc-to-help, generated in Help 2 and "mshcmigated" to mshc files. Can Version builder be used as well in this case?

    Claudette

    Friday, September 2, 2016 6:36 PM
  • Hi again,

    I just tried using different naming methods, the result is the same. For some reason, the content manager does not seem to use the topic version or the guid information when merging the information, only the Help.Id, which is the same. I'm not sure however what you mean when you suggest to use "at least one conceptual topic and make it the parent of the API content.  That will avoid duplicate namespace entries at the root level in the TOC." How would I do that? The two projects have different names at the root level.

    Claudette

    Friday, September 2, 2016 10:16 PM
  • In each help project, you'd add a content layout file containing a conceptual topic with the API Content option set to "Insert as child of this topic".  It sounds like perhaps you've already done that.  Looking at it again, I see the help ID is the fully qualified member name, not the generated ID used to name the files. As such, I don't think you can use two separate help files that differ only by version as the help IDs will be the same between them.

    Version builder wouldn't be useful for the doc-to-help generated topics.  It only merges the API information into one set of topics and doesn't come into play with conceptual topics.  Visual Studio won't differentiate between versions when looking up an API member.  It only knows what to look up by help ID based on the fully qualified member name (namespace, type, and member name).  If you use Version Builder, only one topic is generated.  The Version Information section in each topic lists to which version the member applies.

    Eric


    • Edited by EWoodruff Saturday, September 3, 2016 6:57 PM
    Saturday, September 3, 2016 6:53 PM
  • Hi Eric,

    I did not have a content layout file as conceptual topic. I was trying yesterday to set such a file. I figured out how to set it up this morning.

    Note that I'm working with shfb 2014.12.20: I wanted to upgrade, but I need to also generate in Help 2, which, as I understand from the release notes, was removed from the latest version. I don't know if upgrading to 2015 (before removing help 2) is worth it.

    By the way, I compared the file contents of the Microsoft documentation for .NET framework 4 and for .NET framework 4.6 and 4.5, which both contain a .NET framework class library with common files: the same file in both have the same help.id! The differences lie with the books and packages, and I can't seem to be able to set them right so that the contents are not merged at install.

    Thanks, Claudette




    Thursday, September 8, 2016 2:12 PM
  • Hi Claudette,

    I'm glad that you have figured this issue out and thanks for sharing your discovery here.

    Please mark your reply as answer which is benefit to other communities who has the same issue. If any questions in future, please feel free to come back.

    Best Regards,
    Weiwei


    We are trying to better understand customer views on social support experience, so your participation in this interview project would be greatly appreciated if you have time. Thanks for helping make community forums a great place.
    Click HERE to participate the survey.

    Friday, September 9, 2016 5:38 AM
    Moderator
  • Hi,

    I meant that I figrured out how to use the content layer file (I had never used them before), but that did not solve my problem. The topics appear duplicated even with them. Sorry for the confusion.

    I can install different versions of Microsoft .net framework class library without any duplication of topics, could anyone from Microsoft help me with this? How do you do it?

    Thanks, Claudette

    Friday, September 9, 2016 1:26 PM
  • Hi Claudette Cedras,

    Sorry for misunderstanding your meaning in your previous reply.

    Please provide the detailed steps about how do you create the custom document for your project to Doc v8 and Doc v9. I will try reproduce your issue in my side based on your steps. Thanks.

    Best Regards,
    Weiwei


    We are trying to better understand customer views on social support experience, so your participation in this interview project would be greatly appreciated if you have time. Thanks for helping make community forums a great place.
    Click HERE to participate the survey.

    Monday, September 12, 2016 9:31 AM
    Moderator
  • Hi,

    I document two sets of toolkits and frameworks: one in version 8, the other version 9. They are basically the same, but V8 will remain as is, while V9 will evolve. The two sets are located in different folders.

    I use Sandcastle (V. 2014.12.20) to document them, and I have one project for each version. Their settings are practically the same. I do not use any plugins or components.

    Settings for V8 are as follows:
    Build page:
    Framework version: .NET Framework 4.5

    Help File page:
    Topic file naming method: Hashed member name
    Presentation style VS2013.
    Check Include root namespace container
    Check Enable namespace grouping if supported
    Maximum group parts: 6

    MS Help Viewer page:
    Help Viewer 1.0 catalog product ID: VS2013
    Help Viewer 1.0 catalog version: 100
    Help Viewer 2.x content catalog name: VisualStudio14
    Starting TOC sort order: -1
    TOC parent topic ID: -1
    TOC parent topic version: 100
    Topic version for this file: 8.3.0.0
    MS Help Viewer SDK link type: ID links within the collection

    Settings for V9:
    Same as for V8 except:
    Help File page, Topic file naming method: GUID (makes no difference if they are same or different)

    MS Help Viewer page:
    Starting TOC sort order: -1
    TOC parent topic ID: -1
    TOC parent topic version: 9
    Topic version for this file: 9

    I install them separately (the title, product, name and package name and link change according to version):

    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>Rep++ 9 Frameworks and Toolkits</title>
    </head>
    <body class="vendor-book">
        <div class="details">
            <span class="vendor">Our company name</span>
            <span class="locale">en-us</span>
            <span class="product">Rep++ 9 for NET</span>
            <span class="name">Rep++ 9 Frameworks and Toolkits</span>
        </div>
        <div class="package-list">
            <div class="package">
                <!-- NOTE: The "name" span value cannot contain any periods! -->
                <span class="name">RepPP_FW_TK_V9</span>
                <a class="current-link" href="RepPP_FW_TK_V9.mshc">RepPP_FW_TK_V9.mshc</a>
            </div>
        </div>
    </body>
    </html>

    That's it. Even though the topic naming method, version, parent version, topic version are different in the settings, the installation merges them. I've tried installing both .mshc files from the same manifest (2 packages), also tried the conceptual topic that Eric described, but the result is the same.

    Claudette


    Tuesday, September 13, 2016 7:34 PM
  • Hi Claudette Cedras,

    When I use Sandcastle generate the document I get the an error BE0038. Since it is a third part tool, I don't familiar with it, I need more time to learn how to use it.

    During this time, I suggest you upload the generated documents to OneDrive and share a public link here. I will download them and compare to check whether there has any attributes in the document causes this issue.

    Thanks for your understanding.

    Best Regards,
    Weiwei


    We are trying to better understand customer views on social support experience, so your participation in this interview project would be greatly appreciated if you have time. Thanks for helping make community forums a great place.
    Click HERE to participate the survey.

    Thursday, September 15, 2016 3:08 AM
    Moderator
  • Hi,

    if I boil down what I need, it is to be able to create a manifest file that allows me to install two .mshc files, which are very similar but not identical, in such a way that their content remains in their own separate hierarchy in the Help Viewer. Any two .mshc files will do.

    Claudette

    Thursday, September 15, 2016 9:02 PM
  • Hi Claudette Cedras,

    Could you share your sample .mshc files to us which can help analysis your files to check what causes this issue?

    Best Regards,
    Weiwei


    We are trying to better understand customer views on social support experience, so your participation in this interview project would be greatly appreciated if you have time. Thanks for helping make community forums a great place.
    Click HERE to participate the survey.

    Tuesday, September 20, 2016 9:33 AM
    Moderator