FAQ‎ > ‎

Help 1.0 RC Notes

Release Candidate is now available via MSDN Subscriber downloads and on the MS public website. 
We updated both H3Viewer and mshcMigrate for those using the RC. These apps still work however with the beta 2 release.

MS are preparing for RTM and code is locked down. Microsoft are working with vendors to address outstanding problems. So applications such as mshcMigrate should protect you from most of these bug (contact us if you see problems). Microsoft will addressed these bugs in a later release.

Changes Since Beta 2

  • Install default is now "Online Help". Microsoft now allow F1 to access local 3rd party help even when in online mode.
    • Special note: For release 1.0 Agent does not start in online mode (unless you make a local F1 call).
      So to run offline viewers such as H3Viewer you must switch to Local (Offline) mode.
  • Registry and File names
    • Registry setting now stored under - [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v1.0]
      (Beta release was HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help3)
      This points to the new Program Files and Library Store location.
    • MSHelpListener.exe has been renamed to HelpLibAgent.exe to match HelpLibManager.exe
    • There is now a 64 bit and 32 bit version of MS Help Viewer. So 32bit app programmers.. when reading the registry you may need to read the 64bit area by specifying the KEY_WOW64_64KEY flag in your registry call.
  • URL Port Number
    • New port number = 47873 (Beta 2 used port 80). See readme (program files) for how to change the default port.
      eg. http://127.0.0.1:47873/help/1/ms.help?method=...
    • Override location for HTTP port is now...
      String value "AgentPort"=<portNum> under key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v1.0
      (in Beta 2 this was "ListenerPort" under key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help3 ). 
  • In Online mode you can not start Agent by simply running HelpLibAgent.exe. I've been complaining about this and hopefully this will be fixed in 1.0 or 1.1. They make a special case for local F1 calls -- these will work in Online mode, start agent and displaying the topic. So for now, all offline viewers and stored bookmarks require Local (Offline) mode.
  • With Selfbranded=false I now get an remote link type icon appearing next to my web links. Cool.
  • HelpLibManager.exe - The /uninstall /silent switches now work. Signing is not required for /uninstall /silent.
    Using /Uninstall without the silent switch currently does nothing very useful -- just opens the HLM application.
  • HelpLibManager.exe /? or /Help now displays a list of available switches.
  • LCTP4 (post RC) release
    • The Keywords data and API URL changes with every release. For LCTP4 you need to add "&category=topic" to the API URL to get back a single topic result.
    • The http: local URL has changed again -- http://127.0.0.1:47873/help/2-6600/ms.help?
      - 2 is the session number (as before)
      - 6600 is the Process ID of the Agent application.
    • Nav pane has a little widget on it that will toggle 3 width states.

Known Problems

Most problems we can automatically fix in the Migrate utility. Microsoft to address most of these after the 1.0 RTM.
  • Although XHTML is required, the code must be actually be XML friendly because of the XMLDocument type classes used by MS Help Viewer 1.0.
    Wikipedia is a good XML reference http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

    • Characters embedded in attribute values or text such ' " &  < >  must be escaped to a HTML or Unicode entity.
      ' = &apos; = &#39;
      " = &quot; = &#34;
      & = &amp; = &#38;
      < = &lt; = &#60;
      > = &gt; = &#62;

    • HTML entities like &reg; are valid XHTML but not valid XML and fail to load into the XMLDocument object.
      This wont be fixed by RTM release so you must convert all simple HTML entities to Unicode entities - &#nnn; or &#xhhh;
      The only exceptions are the 5 valid XML entities above: &apos;&quot; &amp; &lt; &gt; 

      &reg; = &#174;
      &nbsp; = &#160;
      &copy; = &#169;
      &middot; = &#183;
      &iquest; = &#191;
      &eacute; = &#201;
      &oacute;= &#243;
      &trade; = &#8482;

    • Note that all instances of ' " & < > chars in any meta content string will cause a problem:
      • Invalid = <meta name="Microsoft.Help.Keywords" content="*+[<]*" /> 
      • Valid = <meta name="Microsoft.Help.Keywords" content="*+[&#62;]" /> 

    • Script containing "&" in a string is a problem. Manual fix required. 
      • The work-around we found is to use "%26" instead of &, and call the function UnEscape() to convert to back to &.
        EG . This works...
        var ampSep="%26";
        var x="mailto:astark1@unl.edu?subject=MailTo Comments"+ampSep+"cc=ASTARK1@UNL.EDU"+ampSep+"bcc=id@internet.node";
        x = unescape(x);
        document.location.href=x;

  • .mshc file names should not contain more than one ".". eg. file name "my.help.mshc" will not merge correctly.
  • You must use the name HelpContentSetup.msha for the manifest file. Other names will not work in this first release.
  • Images, CSS, and JS files must have a path starting from the root.
    If you have a flat file system (no folders) then there is no problem. If you have a folder, all paths must start at the root.
  • CSS url() property is not currently supported. You can work around this using script apparently. Ask myself or Paul and we'll track down that solution.
  • Inter-topic links like <a href=”xx.htm”> must be in the form <a href="ms-xhelp:///?Id=xxx"> 
    • Inter-topic links do not support #bookmarks. No workaround available for this first release.
Other problems that should be fixed by RTM.
  • After install HLM crashes while adding VS books from the DVD (or readonly location).
    • This will be fixed by RTM. The work around is this... 
      * Copy the \ProductDocumentation folder from the DVD to your hard disk. 
      * Make sure all files are marked NOT readonly.
      * Use HLM "Find Content on Disk" and select the .mshc file in that folder. Now the core VS books should install OK.
  • There is a new offline parameter '&embedded=true' you can use on your offline URLs to hide the navigation section of a page.
    In the RC there is bug where if you are in Online mode and you specify an alternative viewer (via registry setting HelpViewerProgID)
    then help viewer still appends the  '&embedded=true' parameter and the URL returns a 404 error since MSDN online does not know this parameter.
    https://connect.microsoft.com/VisualStudio/feedback/details/536575/f1-help-fails-in-online-mode-when-alternative-viewer-is-used#
Other notes.
  • Each topic should start with the standard XML namespace <html xmlns="http://www.w3.org/1999/xhtml"> -- otherwise we see some rendering problems such as TOC dropout. 
  • It is currently possible to install a package that contains no topics. However it cannot be uninstalled. 
    Installing help topics that do not contain the help meta tags also cause this problem.
  • You will need to give your .mshc files a unique name (eg. Prefix with company name).
  • The URL attribute &embedded=true is used to hide the embedded navigation for a topic. 
    There is small bug: In FireFox and Chrome although the navigation hides, you can still see silver "Search" text overlayed in the top left corner of the browser. This will be fixed after RTM.
  • A bookmark <a href="#bookmark"> is incorrectly transformed to <a href="#bookmark" target="_blank">. So you will find some links that incorrectly open in a new window.
  • In Online mode if you F1 a local help topic (Agent closed and alt viewer defined via HelpViewerProgID registry value),
    Agent will start loading but send the F1 local topic to the default browser instead.
  • If another statement immediately follows <script ..></script> on the same same line then the statement is ignored.
    • <script language="javascript" type="text/javascript" src="test.js"></script><title>Errors Test</title>
      So in this case title is ignored and wont appear in the TOC. -- Bug Reported
  • Keywords API call broken when changing catalogs, When I start working with a new catalog I need to restart Agent to read the keywords for the new catalog.

Comments