What is the best way to add custom tags to conceptual content?

Topics: Developer Forum, User Forum
Feb 1, 2012 at 5:00 PM

I have custom HTML that I would like to place in my conceptual files and would like to know what the best practice is for creating custom tags to apply the html.

Example 1)

css definitions


    color: red;


<span class="required">My Text</span>

Instead of adding the span tags I would like to define something like <required>My Text</required> that would then get replaced with the span tag shown above.

Also ideally I would to do this in a way that does not alter the sandcastle default files if possible so that a future update to the sandcastle project will not loose my changes?

Feb 1, 2012 at 7:39 PM
Edited Feb 1, 2012 at 7:40 PM

You'll need to modify the Sandcastle XSL transformations for the conceptual content so there isn't a way around that.  You could isolate your changes in a separate XSL file and then all you'd need to do is add an include in main_conceptual.xsl to pull it in.  That would minimize the changes to the default transformations.

Going forward, if the additions are general enough and other may find them useful, we could just add them to Sandcastle too.



Feb 1, 2012 at 8:42 PM

Thanks for the quick response. I have looked over the file and see what I need to do in order to add my custom tags so will give it a go and see if I get it to work. As for the comment about if they are general enough adding them to Sandcastle I guess I can only outline what I need and see if you think they are general enough that the should be added.

Tags I would create. This to be able to color text I put in my help files like (required) as red, (optional) as orange, (notimplemented) as blue

<required /> replacement html <span class="required"></span>

<optional /> replacement html <span class="optional"></span>

<notImplemented /> replacement html <span class="notImplemented"></span>

Any other way to this type of replacment other than XSL?

For instance would be cool if you had something like your resources or tags in which you defined a tag name and gave it the replacement text. Something like 


<span class="required>{0}</required>

And then the template engine came along and took this <required>My Required Text</required> and replaced it with <span class="required">My Required Text</span>


Feb 1, 2012 at 8:49 PM

One might read my previous post and ask why not just put the HTML directly in the AML file versus creating custom tags and for me it is so that one can change the rendering of the HTML to something different and avoiding putting HTML at all in my XML files.

Every time I want to do something not already offered as a MAML tag it feels like a departure and allows individuals in our company to not follow a standardized approach. By keeping HTML out of the files it then allows us to create stylesheet entries to control fonts, colors, etc... and simply change it in the future.

Having everyone that wants to add RED text know they have to add <span class="required"></span> is what I am trying to avoid.

Feb 2, 2012 at 7:39 PM

Your reasoning for not adding HTML to the MAML topics is sound.  The purpose of MAML is to separate the content from the presentation style so that you don't have to modify the topics when the style changes.  An alternate approach to modifying the XSL transformations is to write a build component that runs in the BuildAssembler step to replace the elements.  However, for something simple like the tags above, modifying the XSL is quicker and simpler.



Mar 15, 2012 at 10:16 PM

Eric, can you provide me a step by step for adding one of these.

Example: want to define <required></required> and when found replace with <span class="required"></span>

I created something like this in Sandcastle\Presentation\v2005\transforms\main_conceptual.xsl but not sure what to do in order to get it to be applied.

 <xsl:template match="required">
  <span class="required"><xsl:apply-templates /></span>

Mar 17, 2012 at 7:37 PM

I think you're almost there.  Prefixing the element name with the MAML namespace "ddue:" as in <xsl:template match="ddue:required"> will probably get it to recognize the element and write out the HTML for it.  If not, let me know and I'll go figure it out.



Mar 21, 2012 at 8:38 PM

Eric, that fixed it up.

<xsl:template match="ddue:required">
      <span class="required"><xsl:apply-templates /></span>

Mar 21, 2012 at 9:32 PM

Eric, how do I update the schema to add intellisense support for these custom tags that I am creating?

Mar 22, 2012 at 2:18 AM

I'd create a separate XSD file so that you don't lose your changes.  All you need to do then is place it in the same folder as the other MAML schemas (typically C:\Program Files (x86)\Microsoft Visual Studio 10.0\Xml\Schemas\MAML).  Add your file to C:\Program Files (x86)\Microsoft Visual Studio 10.0\Xml\Schemas\MAML\catalog.xml and it should pick it up automatically.  If the schemas are ever reinstalled, your file should still be there and you'll just need to add it back to the catalog file.  You'll need admin priviliges to update the files in the folder.

As far as creating the XSD file, you can probably just make a copy of one of the smaller existing ones like structureMedia.xsd and replace its content with the definitions for your elements.  If you need an example, copy the template for something like the legacyBold element as yours appear to be similar to it.  You'll find it in inlineCommon.xsd.  Looking at that file, it may be necessary to add your elements to the inlineCommonGroup definition at the end of that file too.  If it won't recognize your elements as valid, that may be the case.  The only workaround to not having to add them there would be putting your elements in a different namespace so that they can be separated from the normal MAML elements.  The schemas contain "##other" extension points added by the patch that allow for elements in foreign namespaces as children of the common MAML block and inline elements.  You'd then need to include that namespace declaration in any topics that use them and prefix the elements with your namespace ID.  The XSL transformations for your elements would need updating to use the same ID as well in that case rather than "ddue:".



Mar 23, 2012 at 5:30 PM

Thank you for all your help. Will give your suggestion a try.