This project has moved and is read-only. For the latest updates, please go here.

XML Content File to Topic File?

Mar 12, 2009 at 7:07 PM
Is there a quick and dirty way to transform an XML file into a topic file? The reason I ask is because I've found that building these documents in Visual Studio (especially with IntelliSense) is an order of magnitude faster - but if I start by trying to build a topic file the IntelliSense complains that it doesn't recognize the file. (The only thing missing that I wish VS had is the HTML encoding feature in SHFB, which can be a godsend - perhaps a macro would do the trick...)

Is it because I am not importing all of the schema definitions I need to?

Mar 12, 2009 at 8:39 PM

Do you mean build it in order to preview what the HTML for the MAML content looks like?  If so, no you can't build it within Visual Studio.  It's something I plan on supporting when I create the VSPackage for SHFB but that's going to take a while.  Regarding Intellisense, I have some instructions on how to import the schemas into Visual Studio's schema cache at home so I'll post them here later.


Mar 12, 2009 at 8:48 PM
I only meant writing out the documents -- I can live with the existing previewing and compiling options/requirements - just looking for a faster way to write 'em. Looking forward to the schema cache instructions, and the VSPackage.

Thanks again
Mar 13, 2009 at 3:16 AM
Edited Mar 13, 2009 at 8:16 PM
This was sent to me by another user for inclusion in the MAML Guide.  I haven't had a chance to try it out yet so let me know if you run into problems and I'll look into it.

Integrate MAML Schema files into Visual Studio

These instructions assume that Sandcastle is installed in C:\Program Files\Sandcastle and Visual Studio is installed in C:\Program Files\Microsoft Visual Studio 9.0 (VS2008) substitute your install paths as needed.  This should work for VS2005 as well.

  1. Copy all files from C:\Program Files\Sandcastle\Schemas\Authoring to a temp folder where you can edit the files.

  2. Delete the following files:

    • space.xsd

    • __internal.xsd

    • *.xsx

  3. Open file developerStructure.xsd and goto line 37. Change the schema location to "xml.xsd":

    <import namespace="" schemaLocation="xml.xsd"/>

    Save the file.

  4. Rename the file xlink.xsd to xlinkMaml.xsd.

  5. Copy the file C:\Program Files\Microsoft Visual Studio 9.0\xml\Schemas\xlink.xsd to the temp folder.

  6. Open the file xlink.xsd and add an include to the file xlinkMaml.xsd:

    <xs:schema xmlns=""
    elementFormDefault="qualified" targetNamespace=""
        <xs:import namespace=""
        <!-- PATCH HERE -->
        <xs:include schemaLocation="xlinkMaml.xsd"/>

    Save the file.

  7. Copy all files to C:\Program Files\Microsoft Visual Studio 9.0\xml\Schemas.    

    Note: This action will overwrite the file xlink.xsd so you might want to make a backup first.

That's it.

Mar 13, 2009 at 5:18 PM
If I create documents this way, how do I refer to them in SHFB? I had done something similar before and was on a roll up until I found that I had to wrap everything with <topic> tags. Is there a workaround for that, or am I going to have to bite the bullet and create something to automate that part myself? Or does the tool have a way to import XML documents without the <topic> wrapper ?

Thanks for the update, Eric! I really appreciate it.
Mar 13, 2009 at 8:24 PM
In SHFB v1.7 MAML files didn't require a <topic> tag.  However starting with v1.8, they do require a topic tag.  This makes the content layout file easier to manage as it doesn't have to know the location of the file.  It matches them up based on the unique ID and you can move the files around on disk at will.  You can use the Tools | Create GUID option in Visual Studio to create GUIDs for the new topics.  You can add any topic you create outside of SHFB to the content layout file by selecting the Add Existing Topic File or the Add All Topics in Folder from within the content layout file editor in SHFB.