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

How to add XML / HTML comment in conceptual topic page

Topics: Developer Forum, User Forum
Jan 24, 2013 at 12:26 PM


I want to add SVG image (with hyperlinks) together with HTML image map fallback (in case SVG is not supported in help browser) to my conceptual topic page, but since Internet Explorer 9 and older and CHM viewer do not have full support for SVG 1.1, I am using IE specific conditional comments like in the following topic markup snippet:

	<!--[if gt IE 9]>--><object xmlns="" type="image/svg+xml" data="../media/diagram.svg"><!--<![endif]-->
	  <map id="diagramMap" name="diagramMap">
		<area shape="poly" alt="Class 1" title="Class 1" href="T_MyNamespace_MyClass1.htm" coords="19,304,171,304,171,190,19,190,19,304"/>
		<area shape="poly" alt="Class 2" title="Class 2" href="T_MyNamespace_MyClass2.htm" coords="19,152,171,152,171,114,19,114,19,152"/>
		<area shape="poly" alt="Class 3" title="Class 3" href="T_MyNamespace_MyClass3.htm" coords="0,114,266,114,266,0,0,0,0,114"/>
	  <img src="../media/diagram.png" alt="MyNamespace class diagram" border="0" style="border-style:none;" usemap="#diagramMap"/>
	<!--[if gt IE 9]>--></object><!--<![endif]-->

Unfortunately, this doesn't work because comments are not picked when generating output HTML pages.

Is it possible to somehow enable comments to be passed to output HTML page when they are contained inside <markup> tag?

My current workaround is custom SHFB plug-in which hooks in after ExtractingHtmlInfo build step and adds comments around every object tag on all HTML pages from SHFB Working directory. I do not like to use so heavyweight workaround for so simple thing.



Jan 24, 2013 at 4:09 PM
Edited Jan 24, 2013 at 4:14 PM

It would appear that the default behavior of XSLT is to strip comments.  From what I could find, adding the following template should allow them to pass through.  You can place it in main_conceptual.xsl in the .\Transforms folder of the presentation style you are using.

<xsl:template match="comment()"/>

If that works, let me know and I can add it to the transformations since I don't think it will hurt anything and there aren't any comments in the stuff generated by Sandcastle so no extra stuff should get added unless done explicitly as you have done.



Jan 25, 2013 at 3:23 PM
Edited Jan 25, 2013 at 3:27 PM


I have edited main_conceptual.xsl like you said, but it still doesn't work as I expect.

Comments inside <markup> tag are not copied, only comments between AML tags are copied.

If it is too problematic too fix, you do not need to bother because I have found a way to make SVG work in IE (attributes width and height have to be specified on object tag).

I still had issues with CHM, because it doesn't respect 'target' attribute on 'a' tag (<a href="..." target="_parent">) used inside SVG markup, so I still needed to build SHFB plugin in which <object> tags are removed from HTML pages used in CHM because there is no way to have conditional markup for CHM as for IE.

Is it maybe possible to specify conditional markup for CHM and Website output from within Sandcastle / SHFB?
For example, with the following or similar syntax:

            <!--[if CHM]>-->
              This text will appear in CHM help.
            <!--[if HTML]>-->
            This text will appear in HTML help.

Thank you and regards,


Jan 25, 2013 at 4:10 PM

In "C:\Program Files (x86)\Sandcastle\Presentation\vs2010\transforms\utilities_dduexml.xsl", there is:

  <xsl:template match="text()"
    <xsl:copy-of select="."/>

Perhaps if you changed "text()" to "text() | comment()", it might work then.

Jan 25, 2013 at 4:15 PM
Edited Jan 25, 2013 at 4:43 PM


In either case, a build component is probably a better choice than a plug-in.  The build component runs in the BuildAssembler step as the topics are generated where you have a lot of control.  That would probably be better than post processing the HTML in a plug-in.  The build component would allow you to use custom XML elements and attributes to control how the output is rendered and bypass using the markup element altogether.  Substitution tags can be used in the component configuration to pass in the build formats.



Jan 25, 2013 at 4:42 PM


Your change does fix the issue.  The VS2005, Hana, and Prototype styles pass comments through by default but that template in the VS2010 style prevented the comments from going through.  With the added change, they pass through now as well.  Thanks.



Jan 28, 2013 at 10:38 AM

Thanks for all your help.

I will investigate custom build components more thoroughly and will do just fine for that purpose.