MS Help 3 Primer

MS Help 3 is the new Help system for VS 2010 (10.x) and replaces the older MS Help 2.x (help for VS 7.x, 8.x, 9.x).

FAR offers the following tools for editing Help 3 projects.

FAR TOC & Index Editor - Allows you to edit Help 3 TOC and Index meta tags.
Tag Editor - Edit Help 3 topic meta tags.

For guidance on creating and maintaining Help 3 please see:

http://kb.helpwaregroup.com/ms-help-viewer

Migrating to MS Help 3

TOC & Index Files

The most significant difference between MS Help 3 and older help systems is that Indexes and Table of Contents are defined using topic Meta tags.

Because of this there are several snags you hit when converting older content.

Empty TOC Links	Empty links are not allowed in MS Help 3 TOCs, since TOC items are stored in the topic files. Work-around: FAR generates a blank HTML topic file for the item.
TOC Bookmarks	Bookmarks are not allowed in MS Help 3 TOCs. Work-around: FAR generates a HTML topic file that redirects the user to required topic#bookmark.
Duplicate TOC Links	A topic cannot be used more than once in a TOC. This restriction may lift in future versions of H3. Work-around: FAR generates a HTML topic file that redirects the user to required topic.
Index Keyword Links	MS Help 3 Index file links that jump you to another Keyword are not allowed. Work-around: FAR converts Keyword jumps to real topic links.
Index Popup Links	MS Help 3 Index file links that show a list of links is not allowed. Work-around: FAR converts Keyword popups to in-place topic links.

Maintaining TOC and Index Meta Tags

We recommend you maintain your TOC, Visible Index and F1 Indexes in regular MS Help 2.x .HxT and .HxK files. These files support Unicode (unlike MS Help 1.x HHC/HHK files).

Why do this? You can easily destroy a TOC or Index simply by removing a single topic file, or by accidently duplicating or deleting topic meta information. It's safer to maintain TOC and Index items in a separate file.

Use the FAR TOC & Index editor to export a TOC or Index file to topic meta tags.

Other MS Help 3 Requirements

All topics must contain a Microsoft.Help.Id meta tag. The Id must be totally unique since your topics may be merged with topics from other companies. FAR often uses a GUID (unique computer generated number) as an Id but you can make up your own IDs.
All HTML topic files must in XHTML format. The FAR migrate utility performs a basic conversion for you, then it's up to you to maintain your topics in XHTML format. We'd recommend purchasing a HTML Editor such as MS Expression Web 2 to validate your XHTML format.
In normal TOC editing you can edit the TOC labels and various H2 Properties. In Help 3 editing the TOC node labels have no meaning since document <title> tags define the labels. You will notice that when you Export then Import, the labels will all revert to the document titles.

Compiling MS Help 3 Project

Normally we would use MS Workshop tool to Index and compile your source to a compressed CHM of HxS help file.

MS Help 3 is different. All we need to do is ZIP your content and give the file a .MSHC (MS Help Container) file extension. FAR has built-in PKZIP support, or you can use other utilities such as WinZip.

Your .MSHC help file is indexed (ripped of important information and parsed for search terms) at installation time.

http://www.HelpwareGroup.com/