Shaun McCance
shaunm@gnome.org 2007-2009
Include an editorial comment that's hidden from normal readers.

# Editorial Comments

    mal_block_comment = element comment {
      attribute style { xsd:NMTOKENS } ?,
      attribute * - (mal:* | local:*) { text } *,

      mal_block_title ?,
      mal_block_cite,
      mal_block +
    }

The `comment` element allows you 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 optionally 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.

The `cite` element is a required element that specifies the person making the comment. Writers are highly encouraged to provide a `date` attribute.

# Notas

The `comment` element contains an optional title element, a 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 for more information on external-namespace attributes.

# Ejemplos

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

Drake

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

Drake

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

Rupert

But I saw a mallard dive just the other day.

Drake

Rupert, please see the Wikipedia entry.

# Processing Expectations

In normal processing, `comment` elements are 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 stylistic effect should be used to clearly set distinguish comments from the surrounding content.

If a `title` element is present, it is displayed at the top of the comment. The `cite` my require special processing to dispaly both its inline content and its `date` attribute. Automatic text may be used for this.

# 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.