Managing Comments

You can add comments to any selected area of content within XML documents, with the exception of read-only content. The difference between using comments and tracked changes is that a comment is associated to a selection without modifying or deleting the content.

By default, when you annotate your XML documents, the comments are displayed in the Author mode as callouts (balloons) and they are rendered with a unique name and background for each user. If comments are not currently displayed in callouts, select the Comments option in the Callouts preferences page. Comments are also displayed in the Review view.

Figure 1. Comments in Author Mode

Managing Comments in the Main Editor

You can insert and manage comments directly in the main editing area in Author mode.

Add Comment: To insert a comment at the cursor position or on a specific selection of content, select the Add Comment action from the toolbar (or in the Review submenu of the contextual menu).
Tip: When adding or editing a comment, you can use Enter to insert line breaks and Oxygen XML Author Eclipse plugin will take the line breaks into account when presenting the callout. You can also use Ctrl + Enter to accept your changes and close the dialog box.
Show/Edit Comments: To edit an existing comment that you have added in the main editing area in Author mode, select the Show/Edit Comments action from the toolbar (or in the Review submenu of the contextual menu). The action opens a dialog box that allows you to see and edit your comment at the cursor position. Note that you cannot edit a comment that was added by another user, so in that case, the dialog box just displays the comment without the possibility of editing it.
Remove Comments: To remove a comment at the cursor position or multiple comments in a selection, select Remove Comment(s) from the toolbar (or in the Review submenu of the contextual menu).
Copy/Paste: If you copy content that includes comments, they will be preserved when you paste it.

Managing Comments in Callouts

As long as the Comments option is selected in the Callouts preferences page, comments are also displayed in callouts. By displaying the comments in callouts, you then have access to even more actions, such as the ability to reply or mark them as being done. When you right-click a specific comment in its callout, the contextual menu includes the following actions.

Reply: Opens a dialog box that allows you to add a reply to a comment or Tracked Changes. When replying to a comment, the dialog box shows the entire conversation in the comment thread, starting with the first comment added in the particular thread, followed by all the replies. After replies are added to a comment thread, they are displayed with an indentation in the callouts and Review view.
Mark as Done: A toggle action that marks or unmarks a comment or comment thread as being done. It is also available for Tracked Changes that are displayed in a callout. When a comment or change is marked as done, the callout is grayed out and cannot be edited unless the action is toggled to the unmarked state. The action applies to the particular comment and all of its descendents. This is useful for marking comments or changes that have been addressed, leaving only those that still need some attention.
Show/Edit Comment: Opens a dialog box that displays the discussion thread and allows the current user to edit comments that do not have replies. If you are not the author who inserted the original comment, the dialog box just displays the comment without the possibility of editing it.
Remove Comment: Removes a selected comment. If you remove a comment that contains replies, all of the replies will also be removed.
Callouts Options: Select this option to open the Callouts preference page where you can configure various callout options.

Tip: When adding, editing, or replying to a comment, you can use Enter to insert line breaks and Oxygen XML Author Eclipse plugin will take the line breaks into account when presenting the callout. You can also use Ctrl + Enter to accept your changes and close the dialog box.

Managing Comments in the Review View

The Review view is also useful for managing comments. In this view, comments are presented in a compact form, in the order they appear in the document, along with tracked changes. You can also use this view to search for specific comments and it includes some filtering options (for example, you can filter it to only show comments for a particular author). When you right-click a specific comment in the Review view, the contextual menu includes the following actions.

Reply: Opens a dialog box that allows you to add a reply to a comment or Tracked Changes. When replying to a comment, the dialog box shows the entire conversation in the comment thread, starting with the first comment added in the particular thread, followed by all the replies. After replies are added to a comment thread, they are displayed with an indentation in the callouts and Review view.
Mark as Done: A toggle action that marks or unmarks a comment or comment thread as being done. It is also available for Tracked Changes that are displayed in a callout. When a comment or change is marked as done, the callout is grayed out and cannot be edited unless the action is toggled to the unmarked state. The action applies to the particular comment and all of its descendents. This is useful for marking comments or changes that have been addressed, leaving only those that still need some attention.
Show/Edit Comment: Opens a dialog box that displays the discussion thread and allows the current user to edit comments that do not have replies. If you are not the author who inserted the original comment, the dialog box just displays the comment without the possibility of editing it.
Remove Comment: Removes a selected comment. If you remove a comment that contains replies, all of the replies will also be removed.
Show only reviews by '<author name>': Filters the comments to only show comments for the particular author.
Remove all Comments: Removes all comments from the document.

Comments XML Source Code

The comments are stored in the document source code as processing instructions that contain information about the author name and the comment time:

<?oxy_comment_start author="John Doe" timestamp="20090508T164459+0300" 
 comment="Do not change this content"?>
    Important content
<?oxy_comment_end?>

Replies to comments are stored in the document source code as a comment (with information about the author name and time), but with a @parentID attribute and its value is the same as the @id value of the parent comment.

<?oxy_comment_start author="Tom" timestamp="20160217T102630+0200" 
comment="We should not forget about recycling the oil and oil filter!" 
parentID="vws_x4l_1v" mid="4"?>