FAQ‎ > ‎

Help 1.0 Notebook

MS Help Viewer 1.0 notes. 

Note: Some issues below will have been fixed in Help Viewer 1.1 (now available via VS SP1 download).

MS Help Viewer 1.0 Topic Formatting Rules

Header meta tags required by MS HV 1.0 topics.

Each topic must contain...
  • One <title>text</title>
  • One <meta name="Microsoft.Help.Id" content="SomeUniqueId" />
  • One <meta name="Microsoft.Help.Locale" content="en-us" /> 
  • One <meta name="Microsoft.Help.TopicLocale" content="en-us" />
Each topic may optionally contain one of..
  • One <meta name="Description" content="Bla bla bla bla bla bla bla topic desciption." />
    -- This get's displayed with search results.
  • One <meta name="Microsoft.Help.SelfBranded" content="true"/>
    -- Add if you want your own branding (topic .css, Script).
  • One <meta name="Microsoft.Help.TOCParent" content="SomePage-Microsoft.help.id"/>
    -- Use "-1" to place your topic in the main catalog TOC.
  • One <meta name="Microsoft.Help.TocOrder" content="0 or Positive Integer" />
    -- Default is 0 (first TOC sibling position).
Each topic may optionally contain one or more keywords and F1 keywords..
  • <meta name="Microsoft.Help.Keywords" content="myKeyword" />
    <meta name="Microsoft.Help.Keywords" content="myKeyword,subKeyword" />
  • <meta name="Microsoft.Help.F1" content="myContextID" />
For more meta tag help see Help Viewer Meta Tags

Other topic requirements
  • Each topic should start with the standard XML namespace <html xmlns="http://www.w3.org/1999/xhtml">
    -- Otherwise we see rendering problems such as TOC dropout.
  • Topics HTML files should be in XHTML format and XML file compatible.

HV 1.0 Links

There are several types of HV 1.0 links:
  • Brief Id links - <a href="ms-xhelp:///id=TopicHelpId"> - At render time Agent expands this to...
  • Page Id links - <a href="ms-xhelp:///?method=page&id=TopicHelpId&product=vs&productversion=100&locale=en-us">
  • F1 links - <a href="ms-xhelp:///?method=f1&query=MyTopicKeyword&product=vs&productversion=100&locale=en-us">
  • Search query - <a href="ms-xhelp:///?method=search&query=SomeText&ProductVersion=100&Product=vs&PageSize=10&PageNumber=1&locale=en-us">
  • Direct links - <a href="ms-xhelp:///?C:\\programData\\Microsoft\\Help Library\\store\\dev10.mshc;/VS-logo.gif">
Then there are Keyword, TOC, TOC Children, TOC Ancestors queries you can run as well.
For more detail see Meta Tags

Which Search Commands are Supported in Help Viewer 1.0?

  • Search is not case sensitive. Search for "StarTrek" finds the whole word "StarTrek" or "startrek". 
  • "StarTre*" - A trailing *, finds all words starting with "StarTre" EG. "StartRecord", "StarTrek".
  • "aa bb" will find all topics containing aa AND bb. Using quotes has no effect in this version.
  • aa OR bb -- OR must be capital. Returns all topics containing either 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 topics for aa but not containing bb.
  • (StarTrek OR Film) AND BoxOffice -- Nesting using brackets is supported.
  • If a query contains two operators that are adjacent to each other, the second operator is ignored.
  • Leading and trailing operators are ignored.

MS Help Viewer 1.0 Bugs and Workarounds

Microsoft are working with help ISVs, such as Helpware (mshcMigrate, FAR HTML 5, H3Viewer), to workaround these 1.0 issues. Most issues should be fixed in the next release (VS 2010 SP1?).
  • Local help does not work in online mode
    • To view offline help content you must open Help Library Manager and select "Choose online or local help" > "I want to use local help". For release 1.0 Microsoft implemented a small workaround where local 3rd-party F1 calls will start Help Library Agent in online help mode. Apart from that one case, Agent and thus offline help will not open in online mode. We expect this to change in a later release so that 3rd party applications can use the MS Help Viewer 1.0 API in online help mode.

  • HTML entities not allowed in topics
    • Although XHTML is required, topics must be XML friendly since MS code uses XML classes such as XMLDocument. This means that only the 5 basic XML entities --  &apos;&quot; &amp; &lt; &gt; are allowed in topics (see Wikipedia).
    • Note that as per XML, 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 (except the 5 XML entities --  &apos;&quot; &amp; &lt; &gt;) although valid XHTML are not valid XML and must be converted to Unicode entities - &#nnn; or &#xhhh; If you don't you will get install errors. Examples:
      • &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:
      • eg. Invalid = <meta name="Microsoft.Help.Keywords" content="*+[<]*" /> 
      • eg. Valid = <meta name="Microsoft.Help.Keywords" content="*+[&#62;]" /> 
    • Note: 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 &.
        Example: This script 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;

  • Limitation on help filenames (.msha, .mshi, .msha)
    • .mshc file names should not contain more than one ".". eg. file name "my.help.mshc" will not merge correctly.
    • Manifest files must be named "HelpContentSetup.msha". Other names will not work in this first release.
    • Will be fixed in MS Help Viewer 1.1?

  • Topic Image, CSS, and JS file links must have a path starting from the root.
    • If you have a flat file system (no folders) then there is no problem. If your help uses folders, then all paths must start at the root of the help
    • This means we can't have common source between say MS Help 2 and MS Help Viewer 1.0. And we can't edit our topics using a standard editor.
    • Will be fixed in MS Help Viewer 1.1?

  • Inter-topic links like <a href=”xx.htm”> must be in the form <a href="ms-xhelp:///?Id=xxx">
    • At runtime these links are transformed into the full Id path link to the file in the library store.
    • Again this causes problems with standard HTML editors, link checkers and using common source.
    • Will be fixed in MS Help Viewer 1.1?
  • CSS url() property is not currently supported. 
    • You can work around this using script apparently.
    • Will be fixed in MS Help Viewer 1.1?

  • Help cannot be uninstalled bug
    • If you install an empty help package, or a help package containing HTML files that do not contain Microsoft.Help.Id meta tags, then the help may refuse to uninstall.
    • Will be fixed in MS Help Viewer 1.1?

  • Help Packages/files must have unique names
    • If vendors install packages with the same name "xyz.mshc" then the second package wont install even though vendor help is stored in separate areas of the help library store.
    • Will be fixed in MS Help Viewer 1.1?

  • Bookmarks <a href="#bookmark"> are incorrectly transformed to <a href="#bookmark" target="_blank">
    • MS Help Viewer 1.0 incorrectly adds target="_blank" to all bookmark only links.
    • Will be fixed in MS Help Viewer 1.1?

  • Inter-Topic Bookmarks not supported yet
    • Linking between topics currently use Id links <a href="ms-xhelp:///?Id=xxx">. This type of link does not support bookmarks because the path is expanded at rendering time (I think using a transform) and any bookmark is incorrectly formatted.
    • Will be fixed in MS Help Viewer 1.1?

  • Agent (and thus local help) will not run in VS Online Help Mode
    • Apart from F1 3rd-party calls HelpLibAgent.exe (required to view local help) wont start in Online mode.
    • This may be OK for Visual Studio, however any 3rd applications which rely on local help are currently crippled by VS online help mode.
    • Will be fixed in MS Help Viewer 1.1?

  • HTML Parser Bug: Title tag missed if immediately after <script> include line
    • If all these statements are on the same line the last statement (in this case the Title tag) is missed by the parser and the topic does not appear in the TOC. -- Bug Reported
      • <script language="javascript" type="text/javascript" src="test.js"></script><title>Errors Test</title>
    • Still a problem in RTM? Will be fixed in MS Help Viewer 1.1?

  • When I change catalogs (via URL), the Index is not updated.
    • This is a known bug in HV 1.0. For now please restart HelpLibAgent tray application to get the new Index info when you change catalogs.
    • Will be fixed in MS Help Viewer 1.1?

  • TocOrder sorts on HelpId instead of topic title.
    • Topics that don't have TocOrder default to 0 which is sort by title. But in reality they are being sorted buy Topic HelpId. Which is not very useful given that sibling topics may be coming from different help files.
    • Topics with same TocOrder should sort by Topic Title not Topic HelpID.

  • Spaces Stripped from HTML
    • Often Agent or the transforms will strip spaces from the HTML.
    • Comment from Bruce Belson:
      • <pre> tags get their whitespace mangled by the Help Library Agent, unless the non-standard attribute xml:space="preserve" is added to the pre element.
    • Others have reported MSDN code examples with spaces stripped, but on my machine it looked ok.
    • Others have reported spaces stripped (Note to self: Markus sent an example).
    • 14-Aug-2010 -- Pages with URLs containing "&embedded=true" (at end of URL) may display missing spaces. Delete this parameter from the URL and the spaces return.

  • Links in <pre> block not expanded
    • Links with a <pre> .. </pre> are not expanded correctly.
    • Reported as fixed in MS Help Viewer 1.1 (VS 2010 SP1)

  • Break <br /> creates 2 lines
    • When the system sees <br /> it changes it to <br></br>. Unfortunately this causes 2 lines to be displayed in most browsers.
    • Still a problem in VS 1.1 (with IE8).

See also: Script workaround code (Paul O'Rears site)

Other Issues

BITS service fails to download online content

When downloading packages or updating you may get one of these errors
HTTP 401-Server Authentication required.
- HTTP 407-Proxy Authentication.

See this article on how to tweak the BITS...


Comments