MAML IntelliSense

Topics: Conceptual Topics
Jun 18, 2008 at 12:06 AM
Edited Jun 18, 2008 at 7:28 PM
Authoring MAML topics is easy with IntelliSense in Visual Studio 2005 and 2008; however, there are issues in both versions of Visual Studio that prevent IntelliSense from working like it should without some manual intervention.

Previously I had linked to a conversation in the Sandcastle project on CodePlex that provided information about the issues and resolutions for each, but since that project no longer exists I'll post the information here.

- Dave

How To: IntelliSense in Conceptual Topics

Using the Schemas Folder in DocProjects and DocSites

When you create a new DocProject or DocSite it imports the MAML schemas into your project.  Look in the Help\Schemas folder.

In VS 2005 you can simply open developer.xsd once and then close it.  Then as long as VS remains open you'll get IntelliSense in all of your MAML topics.

Unfortunately, VS 2008 has a bug that prevents IntelliSense from working without a few manual updates, although you don't have to open developer.xsd at all, so that's a plus.

To get IntelliSense to work in VS 2008: 

  1. Open the topic that you want to edit and then open the VS 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 (xlink.xsd) and (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 not use the two schemas that are provided by VS 2008.  The path to the duplicate schemas are shown on the right.  Just set the Use column to Do not use this schema for the two that aren't located in your project's Help\Schemas folder.
    1. Note:  For the space.xsd schema is required, so make sure that you exclude xml.xsd.  The xlink schemas are the same, but exclude the VS 2008 version just to be safe.

Once you get IntelliSense working for a topic it will always work for that topic, but you still must follow these steps for the other topics.

Using the Visual Studio Schema Cache

An alternative approach to getting IntelliSense is to use the schema cache, but don't forget to delete the Help\Schemas folder in your new DocProjects and DocSites to prevent the issue described above.

Global Schema Cache

To fix the problem with VS 2008 indefinitely, use the global schema cache for all of the schemas, excluding space.xsd, and be sure to update the developerStructure.xsd file by changing the import for space.xsd to use Visual Studio's xml.xsd file instead.  (Note that xlink.xsd is still required and must be included in the schemas cache folder.  As long as the space.xsd problem has been fixed it seems to work, but without it IntelliSense doesn't work since xlink:href will be undefined.)

Copy all of the MAML schemas, except for space.xsd, into a subfolder named MAML under VS's schema cache, which is located at [Install]\Xml\Schemas.  Then update developerStructure.xsd as noted above by using ../xml.xsd as the path in place of space.xsd.  Finally, update the root Xml\Schemas\catalog.xml file by including the following line:

<Catalog href="MAML\catalog.xml"/>

Here's the contents of the catalog.xml file that you should add to the new Xml\Schemas\MAML folder: 

<SchemaCatalog xmlns="">

  <!-- Schemas for MAML -->


  <!-- Place the MAML schemas and this file in a subfolder named MAML

       in Visual Studio's Xml\Schemas folder. -->

  <!-- Do not include space.xsd -->

  <!-- Make sure that the reference to space.xsd is changed to ../xml.xsd

       in the developerStructure.xsd file -->

  <!-- Update VS's root catalog.xml file by adding <Catalog href="MAML\catalog.xml"/> < > href?>< > href?>< > href?>-->


  <Schema href="%InstallRoot%/xml/schemas/MAML/base.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/baseConditional.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/block.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/blockCommon.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/blockSoftware.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/conditionSet.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/developer.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/developerReference.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/developerStructure.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/glossary.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/hierarchy.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/inline.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineCommon.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineLinking.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineSoftware.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/inlineUi.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/structure.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/structureList.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/structureMedia.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/structureProcedure.xsd"


  <Schema href="%InstallRoot%/xml/schemas/MAML/structureTable.xsd"