FAQ‎ > ‎

Help 1.0 Beta 2 Notes

I've found the Beta 2 help release is not ready for full scale integration testing. But ok to play with. 
The mshcMigrate utility is useful but the migrate part wont help you much at the moment (because of the integration problems).

Bugs & Recommendations for Beta 2 Help

  • Use flat folder structure for topics.
    • Put your HTML topic in the root of .mshc help file otherwise images wont show. Images and can be in sub folders.
  • Use .HTM file ext not .HTML
    • using .HTML stops images from showing and crashes Agent app.
  • Use Topic header <html xmlns="http://www.w3.org/1999/xhtml">
    • If you doc has Help 2 tags <MSHelp:???> then use 
      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:MSHelp="http://msdn.microsoft.com/mshelp" xmlns:mshelp="http://msdn.microsoft.com/mshelp">
    • Don't use <!DOCTYPE ...> declaration - Causes Server Unreachable error.
  • For topic links use ms-xhelp://?id - <a href="ms-xhelp:///?Id=xx-a4a857f60bd8">click me</a>
    • Normal links don't work <a href="my filename.htm">click me</a>
  • Include topic tag <meta name="SelfBranded" content="false"/>  (will change next release)
    • Required to make id links work correctly.
    • Sorry all your local CSS and JS wont work. Self Branding TRUE not really supported in this release.
  • Geoff reports that if you use "&nbsp;",  "&reg;", or "&copy;" in a topic, then the topic will render blank.
  • HLM compiler errors are reported in the Event log, however the topic file is not reported which makes finding the error almost impossible
    • EG: "An error occurred while updating local content: System.Xml.XmlException: The 'p' start tag on line 21 position 2 does not match the end tag of 'div'. Line 22, position 4. at System.Xml.XmlTextReaderImpl.Throw(Exception e)   ..."

Notes:
Here is a list of things I've seen in the Beta 2 drop.
  • Inter-page Links 
    • Links between pages don't work
      • Standard link <a href="filename">click me</a>
        • No supported yet.
      • ms-xhelp links  <a href="ms-xhelp:///?Id=xx-a4a857f60bd8">click me</a>
        • Currently works if the topic includes <meta name="SelfBranded" content="false"/> in the topic header.
        • This is the way the VS help currently do their links.
    • File Links <a href="ms-xhelp:///?Id=xx-a4a857f60bd8">click me</a> are expanded to the full version ms-xhelp:/// page link at rendering time.
  • Images
    • <img src="image.gif"> Images links are not parsed correctly unless the HTML file is in the root of the help file.
      • a topic file in \HTML folder that links to image file in \HTML\Images wont show. And wont show if the image is in the same folder. But images will show if the HTML topics are in the root of the .mshc help file.
    • Name your topics with a .HTM file ext. Currently If you use .HTML the images wont show and Agent may crash.
  • Style & Branding
    • dev10.mshc;/branding.css - is the style sheet that every page uses. In the future they will apparently all 3rd parties to have more control.
      • The branding package is available in the program files directory. You can decompile it and examine the files.
    • The branding CSS is used heavily by MS documentation. If we want to have documentation that looks like MS docs we will need to learn it (I assume).
      • <body class="primary-mtps-offline-document">
        • <div class="topic">
          • <div class="title">Microsoft Help 3.0 Documentation</div>
          •  <div id="mainSection">
          •  <div id="mainBody">
    • Notice there is a /BrandingPackage switch for HLM. http://kb.helpwaregroup.com/ms-help-viewer/hvinfo
      • According to Paul O'Rear [MS] you can apply your own branding package but it works at the Catalog level. So you could make another catalog with your own branding but that does not help VS Integrators. So for VS Beta 2 help we are stuck with the Microsoft branding and feedback links etc.
  • Help Library Manager
    • HelpLibManager.exe - command line switch /UNINSTALL does not work in the beta. Instead run HLM and select "remove content".
    • HLM is the only way to install/uninstall for the Beta. It's incredibly manual unless you have a certificate for signing a cab file in which case you can use the /SILENT switch..
  • Help Library Agent
    • In this version it is called the Hep Listener.
    • When I uninstall and reinstall a book, I have to restart Agent. To do this right click the Agent app in the taskbar tool tray and select close. Reopen by pressing F1 in VS 2010. Or reopne by opening a ms-xhelp:/// URL using window shell (Run or ShellExecute())
  • Branding
    • In this version you will see "Help 3" everywhere. However the final name is likely to be "MS help Viewer 1.0".
  • Search
    • Search for "StarTrek" finds the whole word "StarTrek" or "startrek" (Not case sensitive). 
    • "StarTre*" - Trailing wildcard finds all words starting with "StarTre" EG. "StartRecord", "StarTrek".
    • "*tarTrek" - Leading wildcard not implemented in Beta 2.
    • "aa bb" will find all topics containing aa AND bb. Using quotes has no effect in this version.
    • "A Phrase" - Quoted phrase not implemented yet. Use () to nest instead.
    • aa OR bb (OR must be capital) - returns all results for both aa and bb.
    • aa AND bb (AND must be capital) - returns all topics containing both aa and bb. Same as "aa bb"
    • aa NOT bb (NOT must be capital) - returns all results for aa but not containing bb.
    • aa NEAR bb (NEAR must be capital) - not implemented in Beta 2.
    • (StarTrek OR Film) AND BoxOffice - Nesting using brackets is supported.
  • Compiling
    • Don't use a <!DOCTYPE > statement in your topics. Causes a Server Unreachable error during compiling.
    • MS Help 2 header tags <MSHelp:???> cause compile errors.
      • Include these <HTML> XML Namespaces and the compiler will except the H2 tags.
        <html xmlns="http://www.w3.org/1999/xhtml" xmlns:MSHelp="http://msdn.microsoft.com/mshelp" xmlns:mshelp="http://msdn.microsoft.com/mshelp">
    • I found even a basic heading worked fine with Beta 2 Help. Both ANSI and UTF-8 worked ok for me.
      • <?xml version="1.0" encoding="utf-8"?>    <<--- Make no difference including this line. MS examples include it.
      • <!DOCTYPE >   <<-- Don't include this line... Causes Server Unreachable error
      • <html xmlns="http://www.w3.org/1999/xhtml">   <<-- Required.. When I removed xmlns="" the page did no render correctly. CSS no longer effective.
      • <head>  .. etc
  • Required meta tags
    • <title>text</title>
      • Required(1)
    • <meta name="Microsoft.Help.Id" content="SomeUniqueId" />
      • Required(1) - This makes search work.
    • <meta name="Description" content="Bla bla bla bla bla bla bla topic desciption." />
      • Optional(1) - Shows a description line in the search results. 
    • <meta name="SelfBranded" content="false"/> 
      • Required(1) for Beta 2 if you want inter-page links work correctly
        • <a href="ms-xhelp:///?Id=xx-a4a857f60bd8">click me</a>  (where ID is of course the page ID)
      • Note: The self branding stuff is in flux. All this may change in final release.
    • <meta name="Microsoft.Help.Locale" content="en-us" />
    • <meta name="Microsoft.Help.TopicLocale" content="en-us" />
      • Optional(1) - MS recommend you includes these. However if I ommitt them and the topic seems to safely default to en-us.
        • I created a topic with a French locale tags but in Beta 2 this had no effect on searching or linking to the topic.
          <meta name="Microsoft.Help.Locale" content="fr-fr" />
    • <meta name="Microsoft.Help.TOCParent" content="SomePage-Microsoft.help.id"/>
      • Optional(1) - Makes the page show in your TOC.
        • Use "-1" or any non-existant ID to have no TOC parent.
        • Paul O'Rear [MSFT]: -1 will actually be used to indicate that the topic should be a root node.
          This is not currently functioning correctly in the Beta 2 drop, but that is how it will work for RTM.
        • Paul also notes:  We had a bug with not supporting more than one root node in the TOC. So to get your content to show up in the TOC, you'll either have to make one of the other VS topic nodes a parent to your content (use it's Id as the parent node for your root node), or in order to see only your content's TOC, do a search to find a topic in your content. You'll then see only your content's TOC as an orphaned TOC fragment. Hope that makes sense.
    • <meta name="Microsoft.Help.TocOrder" content="Int-Topic-Order" />
      • Optional(1) - If you ommitt this tag or use an invalid value it defaults of "0" (first child position). If 2 topic siblings have the same Topic-Order they are sorted by name.
        • Range is 0..ABigIntegerNumber
    • <meta name="Microsoft.Help.Keywords" content="Some Keyword" />
      • Optional(*) - If 2 topics shared the same keyword "StarTrek" then search results for "StarTrek" would show both topics.
      • <meta name="Microsoft.Help.Keywords" content="Some Keyword, Sub Keyword" />
        • This 2nd level keyword format really only has meaning in a visible index. Beta 2 does not have a visible index (but H3Viewer does).
Comments