Documentation‎ > ‎

Help File Format

Help file format for HV2 is the same as HV1 but with a few new tags.

Help File Format

HV1 and HV2 use the same file format.

.MSHC Help File

ZIP all your help topics into a standard PKZIP .zip file renamed to .MSHC and you have created a HV help file. MS Help Workshop utility is not required (and not available) for HV help.

Well Formed

The help content must be well formed XHTML. Actually the exact criteria is that the .NET XML reader classes (used in the help engine) must be able to read your HTML topic files. 
So all XML rules apply: All tags must be closed and nested correctly. In moving from CHM or HxS to .MSHC this is the most problematic area in migrating.

Signing and Silent Install

If you encapsulate your help file xyz.mshc into a Cabinet file xyz.cab (note the .cab and .mshc must have the same name), then this can be signed by your programmer. Each cab file can contain one .mshc help file. Only signed cab files can be installed silently. Microsoft's last word I heard was that they recommend NOT signing. I assume this is because of the difficulty most organization have implementing the black art of signing. However Microsoft themselves do sign all their help packages and you are welcome to sign your help as well. See also Paul O'Rear's helpful notes on signing

Meta Tags

Special meta tags define info such as TOC, Index and F1 items. Each topic must be given a unique ID. See Meta Tags section below.

Links 

Link to topics files now use the topic ID or the asset path.
This is why many companies maintain help in say MS Help 2 format (supports Unicode) and use a migration tool in the over-night build to create the .mshc help file. Some high end tools handle single source well but may limit you when custom code is required.
    • Brief Id links - <a href="ms-xhelp:///id=TopicHelpId"> -- At render time this is expanded to a full Id link...
    • Full 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">
You will find that links to images look normal at design time but look something like the "Direct link" above at render time (when doing a Viewer Source).
 
TOC and Index Files are Gone

The traditional Table of Contents and Index files are gone. This information is now stored in the topic file (HTML) headers using special Meta tags. One TOC, one Visible Index, one F1 Index are supported using topic meta tags. A Links and Help 2 attributes are not supported. 

TOC limitations: Because TOC entries are now defined inside topics as meta tags, empty links, duplicate links, bookmarks and remote links are no longer possible in a TOC.
Index limitations: Links to keywords and links containing bookmarks are not supported. 

This has been a brief run-down on the file format. For more info see: http://wiki.helpwaregroup.com/ms-help-viewer/hvinfo

Meta Tags

Each HTML topic file MUST contain ONE of the following meta tags in the header:
  • <title>text</title>  -- Standard title tag is required. This is used as your TOC node label etc.
  • <meta name="Microsoft.Help.Id" content="SomeUniqueId" /> -- Every topic must be given a unique ID. This could be a GUID or something like CompanyName.ModuleName.TopicName.
  • <meta name="Microsoft.Help.Locale" content="en-us" />
  • <meta name="Microsoft.Help.TopicLocale" content="en-us" />
Each HTML topic file MAY contain ONE of these meta tags...
  • <meta name="Description" content="Bla bla bla bla bla bla bla topic desciption." /> -- This get's displayed with search results.
  • <meta name="Microsoft.Help.SelfBranded" content="true"/> -- Add if you want to use your own branding (ie. your own .css, and script). Default is =FALSE (use Microsoft branding and disable links to your CSS and Script).
  • <meta name="Microsoft.Help.TOCParent" content="SomePage-Microsoft.help.id"/> -- So your topic can declare which topic is it's parent in the TOC (even 3rd part or Microsoft topic). Use -1 to parent at the top level.
  • <meta name="Microsoft.Help.TocOrder" content="0 or Positive Integer" /> -- Default is 0 (first TOC sibling position). This allows you order your TOC items.
Each HTML 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" /> -- Use of a comma creates a second level visible keyword. Only two levels are allowed.
  • <meta name="Microsoft.Help.F1" content="myContextID" />

New Meta Tags for HV2

HV2 introduce some new meta tags (these won't break backward compatibility).
  • <meta name=" DisplayVersion" content="My SDK or Module Name" /> 
    Previously in HV1 only Microsoft could set the 'Version' text in the search results. And even then you were restricted to only 7x Microsoft predefined strings.
    In HV2 we have a new meta tag DisplayText so we can set this to any text we like.
    See also: [Forum Post] which discusses this issue.

Migration Tools 

This file format is now quite well supported by several help tool vendors. So please check with your help vendor.

Note that we (The Helpware Group) have create a HV utility that migrates older CHM and HxS help files to new HV file format.
See mshcMigrate. The tool was created in collaboration with the Microsoft MSDN/Help team.
Given the robustness of the MS Help 2 format (Unicode help format used by VS 2002/2003/2005/2008) we usually suggest to clients that they maintain their help in MS Help 2 format then use mshcMigrate.exe to produce .mshc help in the overnight build.


Comments