locked
Help Viewer 2.0 Breaks Self-Branded Content

    Question

  • I've ran into several issues with the Help Viewer 2.0 in VS 2012 when using it with self-branded content.  Does Help Viewer 2.0 still support self-branded content?  Has anyone else ran into these issues?  Is there something I'm missing?  These are the issues I've ran into.  The same help files that I'm installing are working just fine under Help Viewer 1.0 that came with VS 2010.

    1. Help Viewer 2.0 is insisting on using some of its own styles for the page.  Even though my content has its own stylesheet, the text is much larger than it should be when compared to the same content in Help Viewer 1.0.  It's also much larger when compared to Visual Studio's content in Help Viewer 2.0.  In the source for the page I notice it is injecting a set of styles in the page header that are not there under Help Viewer 1.0 and is wrapping the content in a couple of divs that are different than before.

    2. Help Viewer 2.0 is insisting on injecting a div containing the page title right at the top of each page.  My content already has a page title.  I don't want to see it listed twice.  Why is it doing that?  It didn't do it in Help Viewer 1.0.

    3. Help Viewer 2.0 is insisting on making sure that all href values for local content in anchor tags start with "ms-xhelp:///".  That's okay but the way it's doing it is causing broken links since it just overlays the start of the URL with the new prefix with no attempt to fix it properly.  Given the following:

    <a href="ms-xhelp?method=page.....">

    <a href="ms-xhelp://?method=page....">

    You end up with:

    <a href="ms-xhelp:///?od=page.....">

    <a href="ms-xhelp:///?ethod=page....">

    Clicking these links in the content naturally results in "Content not found" errors.  I've fixed my code so that the pages generate the full prefix to work around the issue but still, Help Viewer 2.0 should be correcting the links properly rather than so obviously breaking them.

    4. Related to #3, if you have an href that uses JavaScript, Help Viewer 2.0 completely breaks the link by again overlaying the start of the value with the "ms-xhelp:///" prefix. For example:

    <a href="javascript:SubmitFeedback()">

    becomes

    <a href="ms-xhelp:///ubmitFeedback()">

    Again, broken link and it doesn't work.  I managed to work around this by using a dummy href of "#" and moving the script to an onclick attribute but I shouldn't have to do this to work around an apparent bug in the help viewer.

    There are other problems too with a couple of links and a popup menu at the top of my pages but I haven't figure out why it's broken those yet.

    While we're on the subject, Help Viewer 1.0 had an SDK with documentation.  Is there an equivalent for Help Viewer 2.0 yet?

    Eric


    • Edited by EWoodruff Monday, September 24, 2012 12:05 AM
    Monday, September 24, 2012 12:00 AM

All replies

  • Check your syntax. When SelfBranded is enabled you shouldn't see the VS stuff.


    I've uploaded a simple 4 page example for you to try.

    http://hv2.helpmvp.com/code/help-example

    As you can see my example I have no VS UI showing in my help

    If you really get stuck, feel free to send me a small cut-down example so I can see the problem better.


    Rob Chandler Help MVP www.helpware.net | mshcmigrate.helpmvp.com | hv2.helpmvp.com

    Monday, September 24, 2012 3:12 AM
    Moderator
  • I am having problems with my Help that works fine in MS Help Viewer 1.0 in VS2010, but shows blank in MS Viewer Help 2.0 in VS2012.  If I right click on the right pane and view the source, I can see the source of my HTML file.  I have not dived into it very deep yet, but something has changed though with links and how CSS/JS references are being processed though.

    I will be taking a look tomorrow side-by-side with the source that MS Help Viewer 1.0 and 2.0 are displaying respectfully, even though I am loading the same MSHC files into both.

    Tuesday, October 02, 2012 3:25 AM
  • OK. To debug I usually keep remove parts of the document until it works. So isolating the offending code.

    Once you find it please could you report back here. I'd like to know what's happening also.

    Thanks
    Rob


    Rob Chandler Help MVP www.helpware.net | mshcmigrate.helpmvp.com | hv2.helpmvp.com

    Tuesday, October 02, 2012 11:19 AM
    Moderator
  • Help Viewer 2.0 does appear to have some significant changes in behavior and handling of topics that work just fine under Help Viewer 1.0 as well as some apparent bugs.  Here's what I found when fixing the problems I had.

    The main problem seems to be that Help Viewer 2.0 doesn't handle "SelfBranded" and "Microsoft.Help.SelfBranded" the same way as Help Viewer 1.0.  HV 1.0 doesn't seem to care which one you use but HV 2.0 appears to require "Microsoft.Help.SelfBranded" or it tries to apply the default branding.  The SDK for HV 1.0 mentions that one a couple of times but then proceeds to use "SelfBranded" everywhere else including on the metadata reference page and its included example.  It's not clear what the difference is but HV 2.0 does have a preference for the fully qualified name.  That solved item #2 from my original post.

    Even with the above fix, HV 2.0 still insists on using a larger font for the topics compared to HV 1.0 in some cases (item #1 from my original post).  Since that's only affecting an older presentation style, I haven't tried to find out why.

    Items #3 and #4 from my original post are definitely problems even using your example help file.  There are workarounds as noted but HV 2.0 shouldn't be using such an obviously wrong approach to "fixing" the protocol if that's what it's trying to do.  It shouldn't be doing anything to the ones prefixed with "javascript:" at all.

    The final problem I noted was the broken links and popups that are used at the top of the page in one of the presentation styles.  This problem turned out to be an old "background" attribute for a table cell that specified an image URL.  The help viewer doesn't adjust these by default.  That's not an issue as there is startup script that goes in and fixes them up.  The problem with HV 2.0 is that if it sees such a URL in a background attribute or even in the background-image attribute of a style sheet element it completely halts all processing of the page without reporting any errors.  Since none of the startup script runs, it breaks all the elements that the startup script usually sets up.  Help Viewer 1.0 ignores them and lets the startup script run to fix them up.

    In one presentation style I was able to get rid of the background attribute since there was an image in place within the table cell that the fix-up script was using.  For the one that uses the stylesheet, I ended up with a hack that involved putting the image name in a dummy attribute in an inline style on the page and leaving the background-image attribute out of the stylesheet.  That lets it get by the bug in HV 2.0 and the script can then set the actual image name based on the correct URL and the name from the dummy attribute.

    Regarding RespawnNitemare's issue, I think that's a problem that the current Sandcastle release has too.  It's been fixed for the next release.  I believe it was related to either having some unused XML namespaces on the <html> element or a required namespace being removed from it (perhaps the xhtml namespace declaration).  As in the other cases, HV 1.0 didn't seem to care either way.

    Eric

    Tuesday, October 02, 2012 7:17 PM
  • Thanks Eric for the detailed explanation. I've always used Microsoft.Help.SelfBranded but I remember in the beta of HV 1.0 someone in MS checked the code for me and said they did use either meta tags "SelfBranded" or "Microsoft.Help.SelfBranded". Historic thing I guess. Obviously "SelfBranded" has now been dropped in HV2.

    Glad you are making progress. Can I suggest anything that you are still concerned with you report to
    http://contect.microsoft.com/VisualStudio --- The best place to report bugs.

    It doesn't surprise me that you have had some problems. Their aim was to keep the help source format consistent with HV1 but rewrite the help API engine and rendering. I guess a few things must break in that scenario.


    Rob Chandler Help MVP www.helpware.net | mshcmigrate.helpmvp.com | hv2.helpmvp.com

    Wednesday, October 03, 2012 2:04 AM
    Moderator
  • The final problem I noted was the broken links and popups that are used at the top of the page in one of the presentation styles.  This problem turned out to be an old "background" attribute for a table cell that specified an image URL.  The help viewer doesn't adjust these by default.  That's not an issue as there is startup script that goes in and fixes them up.  The problem with HV 2.0 is that if it sees such a URL in a background attribute or even in the background-image attribute of a style sheet element it completely halts all processing of the page without reporting any errors.  Since none of the startup script runs, it breaks all the elements that the startup script usually sets up.  Help Viewer 1.0 ignores them and lets the startup script run to fix them up.

    Eric, thank you so much for posting this information!  I am using a customized version of the vs2005 Sandcastle presentation, and this issue was preventing the language filter from working, as well as my custom javascript.  I removed the background attribute as you mentioned, and now all the javascript is working properly.

    I also ran into the issue of the help viewer mangling javascript links.  Your solution to use a '#' link with the javascript in an 'onclick' attribute worked for me as well.

    Thanks!

    Wednesday, October 03, 2012 7:17 PM
  • Hi, I have noticed, that the HV 2.0 does not resolve mshelp-links inside <pre>-sections. The HV 2.0 adds a namespase to that <pre> sections in Selfbranded documentations.

    The part of the selfbranded topic before the installation in HV 2.0:
    <pre>
    VAR_INPUT
            NETID           : <a href="ms-xhelp:///?Id=84a1-4238-a86e-952dd5174d64">NetId</a>;
    END_VAR
    </pre>

    After the documentation installation it looks like this:

    <pre xmlns="http://www.w3.org/1999/xhtml">
    VAR_INPUT
            NETID           : <a href="ms-xhelp:///?Id=84a1-4238-a86e-952dd5174d64">NetId</a>;
    END_VAR  
    </pre>
    Monday, December 17, 2012 3:22 PM
  • So <pre> tag preserves both spaces and line breaks.

    In my example below I can still display links. 
    You should report this as a bug to http://connect.microsoft.com/VisualStudio/

    Rob 

    <pre>
    This text is inside span with style
    This is a link
    </pre>
    

    Rob Chandler Help MVP www.helpware.net | mshcmigrate.helpmvp.com | hv2.helpmvp.com



    Rob Chandler Help MVP www.helpware.net | mshcmigrate.helpmvp.com | hv2.helpmvp.com


    Tuesday, December 18, 2012 12:37 AM
    Moderator
  • Links inside <pre>-environments are allowed and the HV 1.x resolves ms-xhelp links inside <pre>-environments.
    Tuesday, December 18, 2012 7:39 AM