Using the Converter

This topic will walk you through using the converter to convert a batch of HTML files to MAML topics.

1. The converter is a console mode application. As such, open a command prompt in order to run it. The utility is located in the .\Extras folder under the root help file builder installation folder (typically C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder).

   Note
   The converter uses an XML file that contains the conversion rules. This file must reside in the same folder as the converter's executable.

2. The converter takes a folder name containing the files to convert as the first parameter and the name of a new folder in which to place the converted topics and supporting files as the second parameter. The folder names must be different but the new folder does not have to exist and will be created if necessary. Below is an example command line:

   Example Command Line

   Copy

   ConvertHtmlToMaml.exe C:\MyLibrary\Doc C:\MyLibrary\Content

   An optional parameter, /companion, can also be specified to create companion files for the converted topics. This is useful if your documentation tool, such as DocProject, makes use of them to store the topic title, help attributes, and index keywords.

   Create Optional Companion Files

   Copy

   ConvertHtmlToMaml.exe C:\MyLibrary\Doc C:\MyLibrary\Content /companion

   An optional parameter, /moveIntro, can also be specified to indicate that the converter should move any topic text preceding the first section element created into the introduction element. This option may produce better results in cases where your HTML topics contain leading text before the first header element, such as an H1 element, that should appear in the MAML topic's introduction element. If your topics lack an HTML header element, this option will typically move the entire topic text into the introduction element which is probably not wanted and the option should be omitted. In that case, a default introduction element is inserted into each topic and you can move text into it during the clean-up phase.

   Move Leading Text to Introduction

   Copy

   ConvertHtmlToMaml.exe C:\MyLibrary\Doc C:\MyLibrary\Content /moveIntro

   Note
   While the destination folder will be created if it does not already exist, it will not be cleared of any existing content. As such, you can convert multiple batches of files into one folder. However, you should rename the conversion log and the supporting files between runs if you want to keep them.

3. As the converter runs, it writes information to the console as it goes. This information is also saved to a log file in the destination folder.

4. Once finished, the review process can begin to clean up any issues and To Do items in the converted topics. The log file can help you locate items that need attention.