Embedded Files
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
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
Converting to MS Help Viewer 1.0 or 2.0
Creating an MS Help Viewer help file is relatively easy:
- All HTML topic files must be in XHTML compliant
- Add the required topic meta tags.
- Convert your TOC, Index & F1 keywords to meta tags.
- ZIP all content to a .mshc (MS Help Container) help file.
- 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
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
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
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
- XHTML Boot Strap (Introducing Microsoft Help Viewer 1.0)
- http://www.w3schools.com/xhtml/xhtml_intro.asp
- http://web4.w3.org/TR/xhtml1/
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
2. Add Topic Meta Tags
Each topic file must contain the following 2 tags.
- A standard HTML Title tag. EG. <title>This is my title text</title>
- 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” />
- See also MS Help Viewer meta tags
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
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.
- See all available MS Help Viewer 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
- 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.
- To Load your TOC, Index or F1 Keywords, select "Import".
- 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).
- 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
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:
- Add all content to be published (HTML, Image etc) to the FAR file list (main window).
- 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
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
Page updated
Report abuse