| Welcome |
Welcome to the HTML to MAML Converter. This utility is used to convert HTML files to Microsoft Assistance Markup Language (MAML) topic files so that they can be compiled into help files using the Sandcastle Help File Builder with the selected presentation style's look and feel. 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).
What is Conceptual Content?
Conceptual content allows you to define non-API documentation that is included in the help file for usage notes, walkthroughs, tutorials, etc. Instead of HTML, conceptual content topics use Microsoft Assistance Markup Language (MAML). This is basically XML conforming to a well defined schema that describes the structure of the conceptual content much like XML comments describe the structure of the code comments. There is no layout or style information within the MAML files. Instead, they are ran through a series of XSL transformations using Sandcastle's BuildAssembler tool similar to the reference (API) content so that they match it in appearance and features. This allows you to utilize the various Sandcastle and third-party build components to alter and extend the presentation style used in the topics.
The term "conceptual content" is actually a catch-all term used to refer to the various types of content that may appear in the help file. MAML actually defines several different content types, each used for a specific type of document (conceptual, glossary, how-to, reference, etc.). Each type has a specific structure with various required and optional XML elements. For more information on MAML, the various topic types, and the various elements that you can use within them, see the Sandcastle MAML Guide.
The Converter Utility
The purpose of this utility is to quickly convert a batch of HTML files (or .topic files used by the Sandcastle Help File Builder) into MAML topics to save you from having to do it manually. Since the conversion to MAML is not perfect, you will still need to review the topics afterwards to clean up any unresolved issues and To Do items noted in the conversion log. The converter will transform the HTML topics into the generic Conceptual topic format. If you require that a topic conform to one of the other MAML topic formats such as Walkthrough, How To, Glossary, etc. you will need to make the necessary adjustments afterwards.
See Also