1.2 (2019-02-09)
Editorial Comments
This is a draft specification. It is likely that changes will still be made before the final specification.
Use the comment element to insert editorial comments into your document. These comments are intended to be displayed only when editing or reviewing the document, and not when the document is viewed by the end reader. A comment element can contain other comment elements, allowing you to have a threaded discussion inside editorial comments.
A comment element may contain a title element to provide a brief description of the subject of the comment. Titles are encouraged in top-level comments, although they are usually unnecessary in replies. A comment element may also contain a cite element to specify the person making the comment. Writers are highly encouraged to provide a date attribute on the cite element.
Notes
The comment element contains an optional info element, an optional title element, an optional cite element, and any general block content.
The comment element can occur in any general block context, including inside pages, sections, and certain block elements.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The comment element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.
Examples
Provide a comment:
<comment>
<title>Mallards Are Dabbling Ducks</title>
<cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
<p>The information in this section is wrong. Mallards are dabbling
ducks, not diving ducks.</p>
</comment>Use comment to carry out a threaded discussion:
<comment>
<title>Mallards Are Dabbling Ducks</title>
<cite date="2009-05-07" href="mailto:drake@example.com">Drake</cite>
<p>The information in this section is wrong. Mallards are dabbling
ducks, not diving ducks.</p>
<comment>
<cite date="2009-05-08" href="mailto:rupert@example.com">Rupert</cite>
<p>But I saw a mallard dive just the other day.</p>
<comment>
<cite date="2009-05-09" href="mailto:drake@example.com">Drake</cite>
<p>Rupert, please see the
<link href="http://en.wikipedia.org/wiki/Mallard">Wikipedia
entry</link>.</p>
</comment>
</comment>
</comment>Mallards Are Dabbling Ducks
The information in this section is wrong. Mallards are dabbling ducks, not diving ducks.
But I saw a mallard dive just the other day.
Rupert, please see the Wikipedia entry.
Processing Expectations
In normal processing, a comment element is not displayed. It may be displayed under various circumstances, such as for writing and editing purposes.
When shown, a comment element is rendered as a displayed block, with each of its child elements interpreted as block elements. A border, background color, or other styling effect should be used to clearly distinguish comments from the surrounding content.
If a title element is present, it is displayed at the top of the comment. The cite element may require special processing to display both its inline content and its date attribute. Automatic text may be used for this.
The optional info element can provide metadata for the comment, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.
Comparison to Other Formats
The comment element is similar to the remark element in DocBook. The DocBook remark element may be used in either a block or an inline context, whereas the comment element may only be used as a block element. The DocBook remark element does not provide a way to supply a title or the name of the person making the remark.
The comment element is similar to the draft-comment element in DITA. The DITA draft-comment element may be used in either a block or an inline context, whereas the comment element may only be used as a block element. In DITA, information such as the commenter's name and the date of the comment are recorded in attributes on the draft-comment element. In Mallard, these are recorded with the cite child element.
Schema
The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the comment element. The namespace declarations for this definition are on the page Pages.
mal_block_comment = element comment {
mal_block_comment_attr,
mal_info ?,
mal_block_title ?,
mal_block_cite ?,
mal_block_comment_content +
}
mal_block_comment_attr = (
attribute style { xsd:NMTOKENS } ?,
mal_block_attr,
mal_attr_external *
)
mal_block_comment_content = mal_block
Mallards Are Dabbling Ducks
The information in this section is wrong. Mallards are dabbling ducks, not diving ducks.