mshcMigrate.exe‎ > ‎

Tour

Migrate

Before migrating go to the Options page and hit "Defaults" button to set the best options for migrating to MS Help 3.0.


Enter the Project file name or Help file name to migrate. 
Enter the Output folder (All files are copies here so source files are not modified).
Hit the Migrate button.



Make sure there are zero errors!  Leaving just one error will cause the merge to fail later at install time.

** Change: Since Build 29 we now renamed files containing XML syntax errors to filename.~removed~.htm
and exclude it from being compiled into the final .mshc help file. So now every migration should in theory merge correctly and be viewable in the MS Viewer.

Click "View Output Folder" to see the results of the Migrate (usually the output folder opens automatically when Migrate completes).

The folder contains
  • _HelpSource - Folder contains the help source. We zip this folder to make the help file.
  • <file>.cab - This is the .mshc help file wrapped in a cab file (required if you want to sign your help).
  • <file>.mshc - This is the help file (A zip of your help content renamed to .mshc file extension). 
  • <file>.Log - Verbose log of the Migration. Contains details of any errors found.
  • helpcontentsetup.msha - You can create this using the manifest page. Required my HLM to merge and test your help file.

Log File

The end of the log (brief onscreen log or verbose file log) displays the number of errors found.

   ** Errors: 3, [ ] Warnings: 0
   Time to complete: 17.5 secs

Each error is prefixed with 2 x asterisks **. So you can easy search and find errors in the log file.

   ** Error: 1 unmatched tag(s) detected. All tags must be closed in XHTML. The following line numbers are estimates only...
    ~ Line 034, Column 003 : <div id="m_divTips" style="margin-top: 5px;">

mshcMigrate fixes most problems automatically but some errors such as missing end <div> tags are impossible to correct automatically.

So use the log to find the location of the error then use your HTML editor (eg. Expression Web 3) to validate and correct the syntax error.

Recompile Help

At this stage we have migrate our help. Required Meta tags have been added. Inter-topic Links have been converted to H3 links.

If you correct some output topics you just need to recompile (re zip the help source).

Go to the Update .mshc page tab. This simply rechecks XHTML syntax and refresh the .mshc help and .cab files.
(However, I think normally you would want to go back to original source and fix the syntax errors there, then re-run the Migrate job).

Manifest file

We now have a .mshc help file but to merge we also require a .msha manifest file. This is just a XML file that defines a book and one or more .mshc (or .cab) files.

The manifest page lets you create "helpcontentsetup.msha" manifest file in the same location as your .mshc (or .cab) files.

NOTE: For version 1.0 the manifest file must be named "helpcontentsetup.msha".

** Change: The Migrate & Update commands now creates helpcontentsetup.msha for you (see the Options page for settings).




Merging Help

To merge our help we use the Help Library Manager. Open HLM and click "Find content on disk".. Locate and select your .msha manifest file to merge your help into the VS\100\en-us catalog. 

For VS 2012 the Content Manager is a tab in the VS 2012 help viewer application.



Alternatively you can open HLM using command line parameters (as your installer would do) and specify the manifest to install.

Here we are merging into the VS\100\en-us catalog using the /sourceMedia switch (in RTM /install switch is no longer required). Note: HLM must be run in elevated mode (Administrator mode) to perform a merge successfully.


Event Log

Help Library Manager uses the Windows Event Log to report errors.

mshcMigrate has a page that monitors the Windows event log and displays any HLM events logged.



Stuck? See the list of support groups on the home page.




Comments