Draft

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>

Mallards Are Dabbling Ducks

from Drake on 2009-05-07

The information in this section is wrong. Mallards are dabbling ducks, not diving ducks.

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

from Drake on 2009-05-07

The information in this section is wrong. Mallards are dabbling ducks, not diving ducks.

from Rupert on 2009-05-08

But I saw a mallard dive just the other day.

from Drake on 2009-05-09

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
© 2007-2016 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard