How To Enable IntelliSense in Conceptual Topics


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 (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 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, 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="">
  <!-- 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"
  <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"

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.

Last edited Jul 1, 2008 at 12:30 AM by davedev, version 1


davedev Aug 29, 2009 at 7:59 PM 
Don't forget that DocProject copies the necessary files from Sandcastle, including the schemas, whenever a new project is created. This way installing Sandcastle updates doesn't break existing projects, although users have the option to create a new project and copy the settings from the old one if they want to upgrade. Forcing users to upgrade isn't such a good thing; e.g., what happens if you are working on a very important project and you don't have time or the desire to upgrade to the latest version of Sandcastle? What happens if you've already customized the XSLT and CSS, and maybe even the MAML schemas, to suit the needs of a particular product or client?

I'll add a work item to offer your solution as an installer option, enabled by default. It does seem like when it comes to the MAML schemas, breaking changes are unlikely.

clugsta Aug 29, 2009 at 1:42 PM 
That's a good point. Like you mention, it seems like a fairly low risk issue. Plus, I'm not sure it is a terrible thing to "force" users to use (or update) to the latest schema. In the long run it will make maintenance easier as Sandcastle is versioned. It also seems that it would be lower risk to the end user when updates to Sandcastle were made. They version Sandcastle, and *if* there were updates to the schema they would immediately see them. Versus the other approach of them copying a schema version from a certain point in time and it falling out of date (possibly to a great degree depending on their processes) when Sandcastle is updated.

Either way, there are now a few approaches to consider. :)

davedev Aug 28, 2009 at 3:16 PM 
Thanks, that's a nice tip. One side-effect though is that you're tying all of your MAML topics to the schemas in the Sandcastle installation folder, so they'll always be forced to use the latest Sandcastle schemas, even if topics are written against older schemas. (It seems unlikely that there will be any breaking changes made to the Sandcastle schemas, so I'll consider adding this solution to DocProject's installer in the next release.)

clugsta Aug 28, 2009 at 12:40 PM 
I believe I have found a slightly easier way to accomplish this. I didn't want to start copying files all over the place, edit the OOTB VS2008 config files for fear they will be overwritten by an update someday, etc. So, I created a file named "authoringcatalog.xml" (name it whatever you wish) and added the following...

<SchemaCatalog xmlns="">
<Association extension="aml" schema="file://C:/Program Files/Sandcastle/Schemas/Authoring/developer.xsd" />

Place this file in the "C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas" directory. This directory is searched at VS start-up, and will find and associate the .aml extension with the proper schema. This allows VS to use the default schema data from the Sandcastle directory without having to copy it and modify any other VS files. This works perfectly with both 2008 and 2005.