You want to insert comments or remarks in your document to enable or disable them in the output format.

For this purpose, DocBook provides a remark element. The following example shows how to use it:

<para>
This is a small text.<remark>Add more content</remark>
</para>

To add comments in your document, there are two methods:

XML comments can be placed almost everywhere in your XML document. It is a very common method to give yourself or others some hints. This can be done with XML comments like in this example:

<para>
This is a text <!-- Ohh, we should add more -->
</para>

However, XML comments have one drawback: They are suppressed during transformation. As such, they are unavailable in your output format and cannot be displayed anymore. Usually, you do not want them to appear in your output.

On the contrary, by using the remark element, comments can be shown or suppressed whenever you want. For example, if you write your document and put in some remarks, you can show them to your contributors for review. After the document is ready to be published, leave the remarks as they are but suppress the remark transformation.

To display or suppress your remarks, use the parameter show.comments. This parameter can appear either on the command line of your XSLT processor or in a customization layer. Any non-zero value shows your remarks whereas a value of zero suppresses them.

When should you use XML comments and when remarks? The following table gives you a quick overview.