FAR HTML 5 and MS Help Viewer 1.0

MS Help Viewer home  > FAR HTML 5 and MS Help Viewer 1.0

See also Introducing Microsoft Help Viewer 1.0

13-April-2009 - Original document
17-Oct-2009 - Updated for the VS Beta 2 release.

Introduction

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

Disclaimer: At the time of writing FAR HTML 5 and MS Help Viewer 1.0 are unreleased products. Features will change before final release.


Converting to MS Help Viewer 1.0

Creating an MS Help Viewer help file is relatively easy:

  1. All HTML topic files must be in XHTML format.
  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 you simply author, ZIP it and ship it.

 

Migration Tool

With Microsoft's help we have developed a migration tool that will convert any Help 2 project or Help file, into MS Help Viewer 1.0 help. The core migration part of the tool is free. The tool is unsupported unless you are a registered FAR HTML v5 user.

 

Steps to Migrating Help

Ignoring the nifty migration tool for now let's talk through the steps required to 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 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 for 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 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 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.

Also see the "MS Help Viewer 1.0" page 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.

Your installer must run HelpLibManager.exe with the following switches

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\Help3]
    AppRoot=C:\Program Files\Microsoft Help\v3.0\
    LocalStore=C:\ProgramData\Microsoft\Help3\

To uninstall you use the /uninstall command line switch and specify the book you want to remove. Something list this...

HelpLibManager.exe /product vs /version 100 /locale en-us /uninstall /silent /vendor "Helpware Inc." /mediaBookList "My book 1" "my book 2" "my book 3" /productName "Helpware Library"

Note

We are still waiting to see how this will all work. My guess is that Installation will not be fully automated for release 1.0.