Office Open XML
17 WordprocessingML Reference Material
17.13 Annotations
17.13.4 Comments

17.13.4 Comments

Comments describe annotations which are anchored to a region of document content, but which contain an arbitrary amount of block-level content stored in their own separate document stories. Within a WordprocessingML document, comments are stored in a separate Comments part within the document package.

A comment in a WordprocessingML document is divided into two components:

  • The comment anchor (the text on which the comment applies)
  • The comment content (the contents of the comment)

The comment anchor is the cross structure annotation which defines the region of text on which the comment in anchored. The comment content is the content stored in the comments part which contains the actual content of the comment.

[Example: Consider a paragraph in a WordprocessingML document whose second word is annotated with a comment:

image

The first component to this comment is the document content which defines the extents of the comment and references the specific comment in the comments part:

<w:p>
  <w:r>
    <w:t xml:space="preserve">Some </w:t>
  </w:r>
  <w:commentRangeStart w:id="0" />
  <w:r>
    <w:t>text.</w:t>
  </w:r>
  <w:commentRangeEnd w:id="0" />
  <w:r>
    <w:commentReference w:id="0" />
  </w:r>
</w:p>

The commentRangeStart and commentRangeEnd elements (17.13.4.4; 17.13.4.3) delimit the run content to which the comment with an id of 0 applies (in this case, the single run of text). The following commentReference element (17.13.4.5) links the preceding run content with a comment in the comments part with an id of 0. Without all three of these elements, the range and comment cannot be linked (although the first two elements are optional, in which case the comment must be anchored at the comment reference mark)

The second component to this comment is the comment content which defines the text in the comment:

<w:comment w:id="0" w:author="Joe Smith" w:date="2006-04-06T13:50:00Z"
w:initials="User">
  <w:p>
    <w:pPr>
      <w:pStyle w:val="CommentText" />
    </w:pPr>
    <w:r>
      <w:rPr>
        <w:rStyle w:val="CommentReference" />
      </w:rPr>
      <w:annotationRef />
    </w:r>
    <w:r>
      <w:t>comment</w:t>
    </w:r>
  </w:p>
</w:comment>

In this example, the comment specifies that it was inserted by author Joe Smith with the initials User via the author and date attributes. It is linked to the run content via the id attribute, which matches the value of 0 specified using the commentReference element above. The block-level content of the comment specifies that

its text is comment and the style of the comment content is based off of the character style with the name CommentReference. end example]

Subsections

Last updated on