Difficulty: ★☆☆ (easy)
Keywords: remarks, show.comments

Problem

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

Solution

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

Example 1.11. A Remark Inside a Paragraph
<para>
This is a small text.<remark>Add more content</remark>
</para>

Discussion

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

  • Use XML comments

  • Use DocBook’s remark element

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.

Table 1.4. Comparison of XML Comments versus Remarks
TopicXML CommentsRemarks
When to use it?

Comments that are only read by you

Comments that can and should be read by others

Where to place it?

Almost everywhere[a]

Restricted by the DocBook schema[b]

Can be displayed and suppressed?No, always suppressedYes, by using the parameter show.comments

[a] An example where you cannot insert your XML comment is inside an attribute.


Project@GitHubIssue#6