xsl:comment


The <xsl:comment> instruction is used to write a comment node to the result sequence.

Changes in 2.0

A select attribute is added in XSLT 2.0, allowing the content of the comment to be defined by an XPath expression rather than by a sequence constructor.

Format

 <xsl:comment   select? =  expression>  <!-- Content:  sequence-constructor -->  </xsl:comment> 

Position

<xsl:comment> is an instruction; it is always used within a sequence constructor.

Attributes

Name

Value

Meaning

select

optional

Expression

Defines the string value of this comment node

The select attribute and the sequence constructor are mutually exclusive; if one is present, the other must be absent.

Content

A sequence constructor.

Effect

The value of the comment is produced by evaluating either the select attribute or the sequence constructor. If neither is present, the comment will be empty.

The sequence produced by evaluating the select attribute or the contained sequence constructor is first atomized, and each item in the atomized sequence is then converted to a string. If the select attribute is present, these strings are concatenated with a single space between adjacent strings; if a sequence constructor is used, they are concatenated with no separator. The resulting string forms the string value of the new comment node. For more details of this process, including error conditions that can arise, see <xsl:attribute> on page 201, which works exactly the same way.

The comment should not include the sequence «-- » , and it should not end in «- » , because these sequences are not allowed in XML comments. The XSLT processor may recover from these errors by adding extra spaces to the comment, or it may report an error. If you want your stylesheet to be portable, you must therefore avoid generating these sequences.

In XML or HTML output, the comment will appear as:

  <!-- comment text -->  

Usage

In theory, a comment has no meaning to the software that processes the output document-it is intended only for human readers. Comments are therefore useful to record when and how the document was generated, or perhaps to explain the meaning of the tags.

Comments can be particularly useful for debugging the stylesheet. If each <xsl:template> in the stylesheet starts with an <xsl:comment> instruction, you will find it much easier to trace back from the output to your stylesheet.

Comments in HTML output are used for some special markup conventions, for example surrounding Dynamic HTML scripts. The purpose of the comment here is to ensure that browsers that don't understand the script will skip over it rather than display it as text. An example is shown below.

Examples

The following example generates a comment showing the date and time at which the output file was generated, and identifying the XSLT processor that was used.

  <xsl:comment>   <xsl:text> Generated on: </xsl:text>   <xsl:value-of select="format-dateTime(   current-dateTime(),   '[D] [MNn] [Y] at [H]:[m01]:[s01]')"/>   <xsl:text> using </xsl:text>   <xsl:value-of select="system-property('xsl:product-name')"/>   <xsl:text> version </xsl:text>   <xsl:value-of select="system-property('xsl:product-version')"/>   </xsl:comment>  

Typical output might be:

  <!-- Generated on: 23 March 2004 at 12:13:02 using SAXON version 7.9-->  

The following example outputs a piece of client-side JavaScript to an HTML output file:

  <script language="JavaScript">   <xsl:comment>   function bk(n) {   parent.frames['content'].location="chap" + n + ".1.html";   }   //</xsl:comment>   </script>  

The output will look like this:

  <script language="JavaScript">   <!--   function bk(n) {   parent.frames['content'].location="chap" + n + ".1.html";   }   //-->   </script>  

The comment cannot be written as a comment in the stylesheet, of course, because then the XSLT processor would ignore it entirely. Comments in the stylesheet are not copied to the output destination.




XSLT 2.0 Programmer's Reference
NetBeansв„ў IDE Field Guide: Developing Desktop, Web, Enterprise, and Mobile Applications (2nd Edition)
ISBN: 764569090
EAN: 2147483647
Year: 2003
Pages: 324

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net