XSLT - Topic 5: Generating Comments with <xsl:comment> in XSLT

Introduction

In XSLT, the <xsl:comment> instruction is used to create comments dynamically in the output document during an XML transformation.

An XML comment is text that is ignored by XML processors but can be useful for developers, administrators, or users who need to understand the structure or purpose of particular parts of an XML document.

For example, an XML comment looks like this:

<!-- This is an XML comment -->

In XSLT, instead of writing a fixed comment directly into the stylesheet, <xsl:comment> allows the comment to be generated dynamically.

The basic syntax is:

<xsl:comment>
    Comment text
</xsl:comment>

Why Use `<xsl:comment>`?

Comments can be useful when the generated XML or HTML document needs additional information that should not be interpreted as actual data.

Common uses include:

Adding explanatory information to generated XML.
Identifying sections of generated output.
Adding transformation-related information.
Including dynamically generated comments.
Helping developers understand generated documents.
Adding debugging information during development.

For example, suppose an XSLT transformation generates a list of employees. You may want the output to contain a comment identifying that the employee section was generated by an XSLT transformation.

<!-- Employee information generated by XSLT -->

Basic Example

Consider the following XML document:

<book>
    <title>Learning XML</title>
    <author>John Smith</author>
</book>

An XSLT stylesheet can generate a comment using <xsl:comment>:

<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

    <xsl:template match="/">
        <book>
            <xsl:comment>This book information was generated using XSLT</xsl:comment>

            <title>
                <xsl:value-of select="book/title"/>
            </title>

            <author>
                <xsl:value-of select="book/author"/>
            </author>
        </book>
    </xsl:template>

</xsl:stylesheet>

The resulting output can be:

<book>
    <!--This book information was generated using XSLT-->
    <title>Learning XML</title>
    <author>John Smith</author>
</book>

The <xsl:comment> instruction has created a comment node in the output.

Static Comments

A static comment contains text that does not change.

For example:

<xsl:comment>Generated by the XML transformation</xsl:comment>

The output will be:

<!--Generated by the XML transformation-->

This is useful when the same comment should appear every time the transformation is executed.

Dynamic Comments

One of the important advantages of <xsl:comment> is that its content can be generated dynamically.

For example, consider:

<student>
    <name>Rahul</name>
    <course>Computer Science</course>
</student>

The XSLT can generate a comment containing the student's name:

<xsl:template match="student">

    <student>
        <xsl:comment>
            Student: <xsl:value-of select="name"/>
        </xsl:comment>

        <name>
            <xsl:value-of select="name"/>
        </name>

        <course>
            <xsl:value-of select="course"/>
        </course>
    </student>

</xsl:template>

The output can be:

<student>
    <!--Student: Rahul-->
    <name>Rahul</name>
    <course>Computer Science</course>
</student>

Here, the comment is not fixed. Its content comes from the source XML.

Using Multiple Values in a Comment

You can combine several values inside an <xsl:comment> instruction.

Suppose the source XML is:

<student>
    <name>Rahul</name>
    <course>Computer Science</course>
</student>

The stylesheet can contain:

<xsl:comment>
    Student Name: <xsl:value-of select="name"/>
    Course: <xsl:value-of select="course"/>
</xsl:comment>

The generated comment may look like:

<!--
    Student Name: Rahul
    Course: Computer Science
-->

The exact whitespace formatting can depend on the XSLT processor and stylesheet.

Using Expressions Inside `<xsl:comment>`

The content of the comment can be created using XSLT expressions.

For example:

<xsl:comment>
    Total Students: <xsl:value-of select="count(student)"/>
</xsl:comment>

If the source document contains five student elements, the output comment can be:

<!--Total Students: 5-->

This makes <xsl:comment> useful for generating information based on the source data.

`<xsl:comment>` with Conditional Processing

Comments can also be generated conditionally.

For example:

<xsl:if test="price &gt; 1000">
    <xsl:comment>Premium product</xsl:comment>
</xsl:if>

If the product price is greater than 1000, the output contains:

<!--Premium product-->

If the condition is false, no comment is generated.

This allows comments to reflect conditions in the source data.

Using `<xsl:comment>` Inside a Loop

It can also be used while processing multiple records.

For example:

<xsl:for-each select="student">

    <xsl:comment>
        Processing student: <xsl:value-of select="name"/>
    </xsl:comment>

    <student>
        <name>
            <xsl:value-of select="name"/>
        </name>
    </student>

</xsl:for-each>

For multiple students, each iteration can produce its own comment.

For example:

<!--Processing student: Rahul-->
<student>
    <name>Rahul</name>
</student>

<!--Processing student: Priya-->
<student>
    <name>Priya</name>
</student>

This can be helpful when examining generated output during development.

Difference Between a Literal Comment and `<xsl:comment>`

There are two different approaches to creating comments in an XSLT stylesheet.

A literal comment can be written directly:

<!-- This is a stylesheet comment -->

This comment belongs to the XSLT stylesheet itself. It is generally not intended to become a comment in the transformation result.

In contrast:

<xsl:comment>This is an output comment</xsl:comment>

is an XSLT instruction that creates a comment in the result document.

This distinction is important.

For example:

<xsl:template match="/">
    <!-- This comment describes the stylesheet -->
    
    <result>
        <xsl:comment>This comment appears in the output</xsl:comment>
    </result>
</xsl:template>

The first comment is associated with the stylesheet, while the second creates a comment in the generated result.

Important Rules

When using <xsl:comment>, certain rules should be kept in mind.

The generated comment must contain valid XML comment content. In particular, XML does not allow -- inside a comment.

For example, this is invalid:

<xsl:comment>
    This is an -- invalid comment
</xsl:comment>

An XML comment also cannot end with a hyphen immediately before the closing delimiter.

Therefore, when dynamically generating comments, the data being inserted into the comment should be handled carefully.

`<xsl:comment>` in HTML Output

Although <xsl:comment> is primarily an XML-related XSLT instruction, it can also be useful when generating HTML.

For example:

<xsl:template match="/">
    <html>
        <body>

            <xsl:comment>
                Page generated using XSLT
            </xsl:comment>

            <h1>Welcome</h1>

        </body>
    </html>
</xsl:template>

The resulting HTML can contain:

<!--Page generated using XSLT-->
<h1>Welcome</h1>

This can be useful for identifying generated sections in the resulting HTML source.

Practical Example

Suppose an XML file contains product information:

<products>
    <product>
        <name>Laptop</name>
        <price>75000</price>
    </product>

    <product>
        <name>Mouse</name>
        <price>1200</price>
    </product>
</products>

An XSLT stylesheet can create comments for each product:

<xsl:template match="products">

    <products>

        <xsl:for-each select="product">

            <xsl:comment>
                Product: <xsl:value-of select="name"/>
            </xsl:comment>

            <product>
                <name>
                    <xsl:value-of select="name"/>
                </name>

                <price>
                    <xsl:value-of select="price"/>
                </price>
            </product>

        </xsl:for-each>

    </products>

</xsl:template>

The resulting document can be:

<products>
    <!--Product: Laptop-->
    <product>
        <name>Laptop</name>
        <price>75000</price>
    </product>

    <!--Product: Mouse-->
    <product>
        <name>Mouse</name>
        <price>1200</price>
    </product>
</products>

This demonstrates how comments can be generated dynamically for individual records.

Advantages of `<xsl:comment>`

The major advantages include:

It allows comments to be generated dynamically.
Comment content can be based on source XML data.
It can help developers inspect generated documents.
It can provide additional information without changing the actual data structure.
It can be combined with conditions, loops, and XPath expressions.
It works with dynamically generated XML and HTML output.
It separates explanatory information from actual data.

Limitations

Comments should not be used as a replacement for actual XML data.

For example, it is not recommended to store important information only in a comment:

<product>
    <!-- Product category is electronics -->
</product>

If the category is important to an application, it should instead be represented as data:

<product>
    <category>electronics</category>
</product>

Applications and XML-processing systems generally treat comments as supplementary information rather than business data.

Conclusion

<xsl:comment> is an XSLT instruction used to create comments in the transformation result. Unlike ordinary comments written in an XSLT stylesheet, <xsl:comment> specifically generates a comment node in the output document.

Its main strength is that the comment can be dynamic. Values from the source XML can be inserted into the comment using XPath and XSLT instructions. It can also be used with conditions and loops, making it useful for documenting generated sections and assisting with debugging and development.

The basic pattern is:

<xsl:comment>
    Comment content
</xsl:comment>

Understanding <xsl:comment> is useful when learning how XSLT does more than simply copy or transform XML elements: it can also construct different types of nodes, including comment nodes, as part of the transformation result.

XSLT - Topic 5: Generating Comments with <xsl:comment> in XSLT

Introduction

Why Use <xsl:comment>?

Basic Example

Static Comments

Dynamic Comments

Using Multiple Values in a Comment

Using Expressions Inside <xsl:comment>

<xsl:comment> with Conditional Processing

Using <xsl:comment> Inside a Loop

Difference Between a Literal Comment and <xsl:comment>

Important Rules

<xsl:comment> in HTML Output

Practical Example

Advantages of <xsl:comment>

Limitations

Conclusion

Why Use `<xsl:comment>`?

Using Expressions Inside `<xsl:comment>`

`<xsl:comment>` with Conditional Processing

Using `<xsl:comment>` Inside a Loop

Difference Between a Literal Comment and `<xsl:comment>`

`<xsl:comment>` in HTML Output

Advantages of `<xsl:comment>`