Topic File

The topic file is used to contain a single conceptual topic. 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 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 build components to alter and extend the presentation style of the topics.

Topic File Structure

MAML 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. When building conceptual content, each topic requires a unique ID in the form of a globally unique identifier (GUID) and a revision number. These are specified in a containing topic element in the content file as shown in this example.

While GUIDs are used throughout this guide and also by default in tools such as the Sandcastle Help File Builder, the IDs can be any value you like. GUIDs ensure unique values by default. If you chose to use more human readable IDs, you are responsible for ensuring that each topic's ID is unique.

Topic Example
<!-- The topic element contains the unique ID and revision number -->
<topic id="303c996a-2911-4c08-b492-6496c82b3edb" revisionNumber="1">
  <!-- This element name will change based on the document type -->
  <developerConceptualDocument
    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
    xmlns:xlink="http://www.w3.org/1999/xlink">

  <!-- The content goes here -->

  </developerConceptualDocument>
</topic>

  Note

The topic element is not part of the MAML schema but is required in order to build the help file. The example topics below include a topic element with placeholder ID and RevisionNumber values. If you copy these files, be sure to replace the ID in each topic with a unique value of your own for each file that you create.

Document Types

See Also