How to add XML / HTML comment in conceptual topic page

Topics: Developer Forum, User Forum
Jan 24, 2013 at 11:26 AM

Hi,

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:

<para>
  <markup>
	<!--[if gt IE 9]>--><object xmlns="http://www.w3.org/1999/xhtml" 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"/>
	  </map>
	  <img src="../media/diagram.png" alt="MyNamespace class diagram" border="0" style="border-style:none;" usemap="#diagramMap"/>
	<!--[if gt IE 9]>--></object><!--<![endif]-->
  </markup>
</para>

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.

Regards,

Mario

Coordinator
Jan 24, 2013 at 3:09 PM
Edited Jan 24, 2013 at 3: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()"/>
  <xsl:copy/>
</xsl:template>

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.

Eric

 

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

Hi,

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:

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

Thank you and regards,

Mario

Jan 25, 2013 at 3:10 PM

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

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

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

Coordinator
Jan 25, 2013 at 3:15 PM
Edited Jan 25, 2013 at 3:43 PM

@Mario:

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.

Eric

 

Coordinator
Jan 25, 2013 at 3:42 PM

@Takajalka:

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.

Eric

 

Jan 28, 2013 at 9:38 AM

Thanks for all your help.

I will investigate custom build components more thoroughly and http://www.codeproject.com/Articles/16740/Creating-Custom-Build-Components-for-Sandcastle will do just fine for that purpose.

Regards,

Mario