MS Help Viewer‎ > ‎

Create a HV Project

See also Introducing Microsoft Help Viewer 1.0

13-April-2009 - Original document
17-Oct-2009 - Updated for the VS HV 2 (VS 2012) release.
20-Feb-2013 - Moved doc to new KB Wiki

Introduction

This document provides a guide to editing Microsoft Help Viewer projects using FAR HTML version 5.


Converting to MS Help Viewer 1.0 or 2.0

Creating an MS Help Viewer help file is relatively easy:

  1. All HTML topic files must be in XHTML compliant
  2. Add the required topic meta tags.
  3. Convert your TOC, Index & F1 keywords to meta tags.
  4. ZIP all content to a .mshc (MS Help Container) help file.
  5. Install the help file.

That's it. Past versions of MS Help required you to compile your help source. 
With MS Help Viewer 1.0  & 2.0 you simply author, ZIP it and ship it. Compilation (building search data etc) happens at install time.

Migration Tool

With Microsoft's help we have developed a migration tool that will convert any HTML Help or MS Help 2 project or help file, into MS Help Viewer 1.0 help.  

 

Steps to Migrating Help

Ignoring the nifty migration tool (MshcMigrate.exe) for now let's talk through the steps required to manually produce Microsoft Help Viewer 1.0 help.

1. XHTML 1.0 Compliant HTML

Each HTML topic file must be XHTML 1.0 compliant HTML.

Create your help topics in HTML as you have done in the past, but be careful to format in XHTML.
Unless your topics are well-formed XHTML/XML the installation will fail. We recommend you use a HTML Editor which validates for XHTML 1.x such as MS Expression Web 3.

XHTML syntax rules are pretty easy to follow

Note that FAR HTML 5 contains a file utility called "Convert to XHTML" used to convert HTML topics to XHTML format. This is the same code as used in the migrate utility.

 

2. Add Topic Meta Tags

Each topic file must contain the following 2 tags.

  1. A standard HTML Title tag. EG. <title>This is my title text</title>
  2. A unique Help ID. EG. <meta name="Microsoft.Help.Id" content="SomeUniqueStrID" />

The Title tag is nothing new to most of us. It must be in the <head> ... </head> section of your topic.

Every topic must have a unique help ID string.  MS often use GUIDs, since these 128-bit integer numbers have a very high degree of certainty of being unique. These identify each document and are used to build TOC and Index structure
EG. <meta name=”Microsoft.Help.Id” content=”"30FE1A89-3189-4899-9BC3-1110A9FE8D6D” />

FAR Tag Editor

Use the new FAR HTML 5, Tag Editor to quickly add/remove help tags. See main menu: Authoring > Tag Editor.

 

3. TOC and Index

In MS Help Viewer there are no TOC and Index "files". Table Of Contents, Visible Index and F1 Keywords are instead stored in HTML topics as meta tags.

FAR TOC & Index Editor to the Rescue

Even though TOC and Index entries are now declared using meta tags in topic file headers, FAR still allows you to edit these using the FAR TOC & Index Editor. To do this use the new Import/Export commands to read/write TOC and Index meta tags.

  • TOC > Export to MS Help Viewer 1.x Meta Tags...
  • TOC > Import MS Help Viewer 1.x Meta Tags...

Also see the "Help 3" page tab in the TOC Editor.

The process is as follows

  1. Add all your projects HTML files to the FAR File List (main window). This is so FAR can read and write meta tags as required.
  2. To Load your TOC, Index or F1 Keywords, select "Import".
  3. The "MS Help Viewer 1.0" page also allows you to specify a parent of your TOC (where in the master TOC it plugs into).
  4. To Save your TOC, Index or F1 Keywords, select "Export".

NOTE

When you import TOC or Index meta tags you will be editing in .HxT or .HxK file format.  We recommend maintain your TOC & Index using the  .HxT/.HxK files, Exporting as required (import not required). This would be a more reliable way to maintain your TOC otherwise deleting a single topic could break your TOC.

 

4. ZIP all content to a .MSHC File

To make the final help file you just need to ZIP your content to a .MSHC file (MS Help Container) using whatever ZIP program your prefer.

To do this using FAR:

  1. Add all content to be published (HTML, Image etc) to the FAR file list (main window).
  2. Use the FAR "Commands > Zip File List" to ZIP the file and rename to .MSHC

That's it. You can now test the help file.

 

5. Deployment

The migration utility has a page where you can test that you your help installs correctly.

Go to the Manifest page, enter the required information and click the "Create Manifest" button. You must ship this .msha file with your .mshc help files. For version 1.0 the .msha file must have the name HelpContentSetup.msha.

For Help Viewer 1.x your installer must run HelpLibManager.exe with the following switches

  • C:\Program Files\Microsoft Help Viewer\v2.0\HelpLibManager.exe /product VS /version 100 /locale en-US  /install /sourceMedia "C:\path\to\HelpContentSetup.msha"

For Help Viewer 2.x your installer must run HlpCtntMgr.exe, or run the VS Help Viewer and install using the Manage Contents page.

  • C:\Program Files\Microsoft Help Viewer\v2.0\HlpCtntMgr.exe /operation install /catalogname VisualStudio11 /locale en-us /sourceuri "C:\path\to\HelpContentSetup.msha"

You will probably need to create a small help application to help the installer find HelpLibManager.exe and run it.

You can find the location of the EXE in the registry...

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v1.0   (for HV1 -- VS 2010)

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0   (for HV2 -- VS 2012)


To Uninstall you use the /uninstall command line switch



Comments