How To Enable IntelliSense in Conceptual Topics

Introduction

Conceptual topics in Sandcastle are written in Microsoft Assistance Markup Language (MAML), which is a collection of XML schemas for structured authoring.

Visual Studio's built-in XML editor can be used to author conceptual topics. IntelliSense can be enabled by providing Visual Studio with the MAML schemas. IntelliSense makes it easy to author conceptual topics in Visual Studio since it provides a list of the XML elements and attributes that are supported by MAML and the context in which they will be used.

For more information and links to resources about MAML, see Sandcastle Help.

The Help\Schemas Folder in DocProjects and DocSites

When you create a new DocProject or DocSite, the MAML schemas from the Sandcastle installation folder are imported into the new project's Help\Schemas folder. Visual Studio will use the schemas found in your project to enable XML IntelliSense for all conceptual topic files (.aml or .xml) within your project.

For more information about conceptual topics in DocProject, see How To Use The Topic Management Dialog.
For help creating a new project, see Creating a DocProject for a New Solution and Quick-Start: Creating a DocSite.

Problem: IntelliSense is Not Enabled in Visual Studio 2005

If you're using Visual Studio 2005 and IntelliSense isn't working for your conceptual topics then try opening Help\Schemas\developer.xsd once, and then close it immediately. As long as Visual Studio remains open you should now get IntelliSense in all of your MAML topics.

Problem: IntelliSense is Not Enabled in Visual Studio 2008

Visual Studio 2008 will not provide IntelliSense for the MAML schemas without a few manual updates due to clashing schema namespaces.

The solution for enabling IntelliSense in Visual Studio 2005 does not work for Visual Studio 2008. Instead, you must manually remove duplicate namespaces from Visual Studio for each individual topic.

Note: To fix the problem with Visual Studio 2008 indefinitely, and for all topics simultaneously, use the Global Schema Cache instead. See the section on the Global Schema Cache below for more information.

To get IntelliSense to work in Visual Studio 2008 using the project's Help\Schemas folder:
  1. Open the topic that you want to edit and then open the standard Properties window.
    1. Note: You must have the topic's content focused, not the node in Solution Explorer.
  2. Open the Schemas... dialog.
  3. Sort by Target Namespace and you'll find two duplicate entries; they are for http://www.w3.org/1999/xlink (xlink.xsd) and http://www.w3.org/XML/1998/namespace (space.xsd and xml.xsd).
    1. Note: If you have more than one DocProject or DocSite in the same solution then you'll see multiple duplicates; delete the Help\Schemas folder from all of the projects except for one and then continue with these instructions so that the two namespaces each have only one duplicate entry.
  4. To get IntelliSense to work you must exclude the two duplicate schemas that are provided by Visual Studio 2008. The path to the duplicate schemas are shown in the right-most column of the Schemas dialog. Set the Use column to Do not use this schema for the two duplicates that aren't located in your project's Help\Schemas folder.
    1. The space.xsd schema is required for http://www.w3.org/XML/1998/namespace, so make sure that you exclude xml.xsd instead.
    2. The duplicate xlink schemas are the same, but exclude the Visual Studio 2008 version just to be safe.
Once you get IntelliSense working for a topic it will always work for that particular topic, but you still must follow these steps again to enable IntelliSense for every topic. See the next section of this article for a better solution in Visual Studio 2008.

Visual Studio's Global Schema Cache

An alternative approach to getting IntelliSense in both Visual Studio 2005 and 2008 is to use the Global Schema Cache.

Just be sure that all of the developers and/or help authors working on the same DocProjects and DocSites are using the same version of the MAML schemas. With each new release of Sandcastle the files in the global schemas cache folder on each computer may need to be replaced with new versions; however, keep in mind that changes to the MAML schemas in the global schema cache will then have an effect on IntelliSense for all topics, even those that were written against previous versions of the schemas. Breaking changes to the MAML schemas seems unlikely though.

Important: Don't forget to delete the Help\Schemas folder in your DocProjects and DocSites to prevent the issue with duplicate namespaces described above for Visual Studio 2008.

To use the global schema cache:
  1. Create a subfolder named MAML under Visual Studio's global schema cache folder, which is located at [VS Install Path]\Xml\Schemas.
  2. Copy all of the MAML schemas from the [Sandcastle Install Path]\Schemas\Authoring folder, excluding space.xsd, into the new MAML schemas folder that you created in the previous step.
  3. Open the developerStructure.xsd file and change the import for space.xsd to use ../xml.xsd instead.
  4. Update the root [VS Install Path]\Xml\Schemas\catalog.xml file by including the following line:
<Catalog href="MAML\catalog.xml"/>

Create a catalog.xml file in the [VS Install Path]\Xml\Schemas\MAML folder that you created previously. The contents of the catalog.xml file are shown below.

<SchemaCatalog xmlns="http://schemas.microsoft.com/xsd/catalog">
  <!-- Schemas for MAML -->

  <!-- 1. Place the MAML schemas and this file (catalog.xml) in a subfolder named MAML
          in Visual Studio's Xml\Schemas folder. -->
  <!-- 2. Do not include space.xsd -->
  <!-- 3. Make sure that the reference to space.xsd is changed to ../xml.xsd 
          in the developerStructure.xsd file -->
  <!-- 4. Update VS's root catalog.xml file by adding <Catalog href="MAML\catalog.xml"/> -->

  <Schema href="%InstallRoot%/xml/schemas/MAML/base.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/baseConditional.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/block.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/blockCommon.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/blockSoftware.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/conditionSet.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/developer.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/developerReference.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/developerStructure.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/glossary.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/hierarchy.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/inline.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineCommon.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineLinking.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineSoftware.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineUi.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/structure.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/structureList.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/structureMedia.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/structureProcedure.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
  <Schema href="%InstallRoot%/xml/schemas/MAML/structureTable.xsd"
          targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
</SchemaCatalog>

IntelliSense should now work for all MAML topics automatically; although, in Visual Studio 2008 you still must delete the Help\Schemas folder from your DocProjects and DocSites to prevent the issue with duplicate namespaces as described above.