mshcMigrate.exe‎ > ‎

Migrate

mshcMigrate.exe converts old help projects (Html Help & MS Help 2) to the new HelpViewer help format used by VS 2010 help / VS 2012 help (and later).

In the first field enter either a help file (.chm or .hxs), help project file (.hhp or .hxc) or a directory containing your help source. Enter a destination folder in the second field and hit the Migrate button. Source files are copied to the destination folder then upgraded to HelpViewer help format. Finally all updated source is zipped to a .mshc help file. The original source files are not modified.

Inputs

The Help input can be either...
  • Path to HTML Help project file (.hhp).
  • Path to HTML Help help file (.chm)  -- Results not as good as .hhp as not all info can be read from a .chm.
  • Path to MS Help 2.x project file (.hxc). 
  • Path to MS Help 2.x help file (.hxs)  -- results same as .hxc.
  • Path to directory containing help source.

Outputs

After migration a help file, say MyHelp.HxS, will have the following output...
  • A folder is created \MyHelp_HxS\
  • MyHelp_HxS\MyHelp.log - Verbose log file. Check for errors by searching for **.
  • MyHelp_HxS\MyHelp.mshc - Output help file.
  • MyHelp_HxS\MyHelp.cab - This just a .mshc file wrapped in a .cab in case you want to sign your help.
  • MyHelp_HxS\_HelpSource\ - Unzipped version of MyHelp.mshc. Also contains the updated MS Help 2.x .Hx? project files.
You can ship your help as either a .mshc or signed .cab file.

Migrate Errors 

Once migration has finished both the on-screen display and the log file will show the number of errors found. These are issues Migrate could not fix automatically (usually XML syntax issues). You must manually fix these errors. Open the log file and search for ** (2x asterisks - All errors are marked with **). 

Even with errors you should be able to go ahead and view the help, since we replace the problem topics with place holders. 

You can either fix the problems in the original help source and remigrate. Or you can repair the migrated help files in the _HelpSource folder, then use the "Update .mshc" page tab to simply check and recompile.

To fix reported format issues open the offending topic files in a program that can validate XHTML such as MS Expression Web 3. 

The MS Help Library Manager is very fussy. If the files are not well-formed XML then merging will fail. So make sure you fix all reported errors. To help merge succeed we rename all topic files containing errors to xxxxx.~removed~.html and excluded them from the final .mshc help file. The original xxxxx.html topic file is replaced with a file that describes the error.

Other Controls:

  • Click "View Output Folder" to open a Windows Explorer window at the output folder.
  • Click "Update .mshc" to recheck HTML syntax of the \_HelpSource files and refresh the .mshc and .cab files.

Process 
Here is the order of execution:
  1. Copy all project and help content to the output folder

    Select either a help file or project file (MS HH 1.x or MS Help 2.x). For MS Help 2.x there is no advantage in choosing one over the other since MS Help 2 has round-trip compiling. For HTML Help 1.x use .hhp project files rather than .chm help files then we can migrate mapping information [MAP][ALIAS] to F1 help meta tags.

    You can also specify a folder as the source. The folder should contain your help source. The root folder can optionally contain a TOC file (.hhc or .hxt), a K Index file (.hhk or .hxk) and/or a F1 Index (.hxk) file. These files are quick to create using FAR HTML 5 TOC/Index editor.

  2. Read TOC & Index files information

    TOC and Index file information needs to be converted to topic meta tag statements. So next the migrate utility reads this information from your old TOC and Index files.

    TOC meta tags define the topic's parent topic and sibling order.
    - <meta name=”Microsoft.Help.TocParent” content=”SomeTopicIdentifier” />
    - <meta name=”Microsoft.Help.TocOrder” content=”SomePositiveInteger”/>

    Visible (K) Index items are defined using...
    - <meta name=”Microsoft.Help.Keywords” content=”SomeKeyword” />
    - <meta name=”Microsoft.Help.Keywords” content=”Level1Keyword,Level2Keyword” />

    F1 Index (F) items are are defined using...
    - <meta name=”Microsoft.Help.F1” content=”ContextID” />

    Associated (A) Index Links are not currently support by MS Help Viewer 1.x. Neither are H2 attributes.

    TOC file notes

    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.

    To resolve these problems mshcMigrate generates temporary topic file placeholders. You can correct these problems later in your own time. Note that during migration TOC file labels are ignored, since MS Help Viewer 1.0 uses topic file titles.

    These temporary fix up files live in the  \_AutoGenerate folder.

    Index file notes

    Links to keywords and links containing bookmarks are not supported by MS Help Viewer 1.x. These links are converted to conventional topic links.

    Note that in Help 2.x popup links use the topic title as their keyword.

    H2 Indexes migrated: "K" & "F" Index keywords only.
    Note: H2 "A" Index keywords and Attributes are not support in MS Help Viewer 1.x.

    1. Migrate all topics

      For each HTML topic file migrate does the following:

      1. Add required topic meta tags.
      2. Add TOC and Index topic meta tags.
      3. Migrate HTML Code *Note1
      - Convert all simple HTML entities (like &amp;) to Unicode entities (like &#38;)
      - Convert all inter-topic <a href="..."> links to <a href="ms-xhelp:///?Id=xxx"> format.
      - Convert all <img src="..."> links to be full path from the root.
      - Remove all inter-topic bookmarks from links (bookmarks are not supported).

      *Note1: Microsoft say they will fix these issues in a later release. So for the time being these issues and work-a-rounds are something we need to live with.

    2. Convert topics files to XHTML and UTF-8 encoding

      After migrating each topic we also perform a basic conversion from HTML to XHTML format.

      The migration utility converts HTML tags to lowercase, closes open tags, adds XHTML header declarations, etc. Problems that cannot be fixed automatically are logged to the output log file as an error with line numbers so you can correct them later.

      Note that the migrate utility is not an XHTML validation tool. We recommend that authors invest in a tool such as MS Expression Web so that your XHTML code is accurately validated.

      Topic files that do not pass the validation test are renamed to filename.~removed~.html and excluded from the final help file.


    3. Zip output to .MSHC help file

      All migrated files (see _HelpSource folder) are zipped to a PKZIP compatible file and the extension renamed to .MSHC (Microsoft Help Container). We also add the .mshc help file to a .cab file incase you want to sign your help.