Edit online

Comments, Highlights, and Tracked Changes

The comments and tracked changes can be made visible in the PDF output by setting the show.changes.and.comments transformation parameter to yes.

Figure 1. Chemistry Annotations in Acrobat Reader
By default, they are shown as PDF text annotations (sticky notes). These are graphical markers in the document content and are also listed in the Comments section when opening the output file in Acrobat Reader.
Note: Comments with the Mark as Done flag selected appear with a check mark in the Comments section and with a Completed label ().

To avoid rendering the elements as PDF annotations and show them as footnotes instead, you can use the show.changes.and.comments.as.pdf.sticky.notes transformation parameter set to no.

The comments and changes are included in the merged map file either as XML elements (<oxy-insert>, <oxy-delete>, <oxy-comment>, <oxy-attributes>) in the case of the XML merged map, or as HTML elements with similar classes (oxy-insert, oxy-delete, oxy-comment, oxy-attributes) in the case of the HTML merged map. Sub-elements contain meta-information about each change.

Tip: These elements are automatically recognized and transformed in PDF annotations when using Chemistry as PDF processor.
Note: The inserted text, deleted text, and deleted markup are included in the sticky notes, you can change this behavior by using the show.changed.text.in.pdf.sticky.notes.content parameter.
Edit online

Comments and Tracked Changes - XML Fragment

This section contains information about how each type of tracked change is structured in the merged map XML file.

Insertions

For an insertion type of tracked change, the structure that defines the insertion details is inside the range (<oxy-range-start> to <oxy-range-end>), the inserted text is highlighted by an <oxy-insert-hl> element, and the details are stored in the <oxy-insert> element.

    <oxy:oxy-range-start id="sc_1" hr_id="1"/>

       <oxy:oxy-insert href="#sc_1" hr_id="1">
           <oxy:oxy-author>dan</oxy:oxy-author>
           <oxy:oxy-content>insert</oxy:oxy-content>
           <oxy:oxy-date>2018/03/15</oxy:oxy-date>
           <oxy:oxy-hour>09:38:29</oxy:oxy-hour>
           <oxy:oxy-tz>+02:00</oxy:oxy-tz>
       </oxy:oxy-insert>

       <oxy:oxy-insert-hl>This is an insert!!</oxy:oxy-insert-hl>

    <oxy:oxy-range-end hr_id="1"/>

Comments

Similar to insertions, comments are defined in a range (<oxy-range-start> to <oxy-range-end>), the comment details is in the <oxy-comment> element, and the highlighted content is wrapped in the <oxy-comment-hl> element.

    <oxy:oxy-range-start id="sc_1" hr_id="1"/>
      
        <oxy:oxy-comment href="#sc_1" hr_id="1">
              <oxy:oxy-author>dan</oxy:oxy-author>
              <oxy:oxy-comment-text>This is a comment.</oxy:oxy-comment-text>
              <oxy:oxy-date>2018/03/15</oxy:oxy-date>
              <oxy:oxy-hour>09:56:59</oxy:oxy-hour>
              <oxy:oxy-tz>+02:00</oxy:oxy-tz>
        </oxy:oxy-comment>
          
        <oxy:oxy-comment-hl>Context</oxy:oxy-comment-hl>
          
    <oxy:oxy-range-end hr_id="1"/>           
Note: Comments that are marked as done have a flag="done" attribute:
<oxy:oxy-comment href="#sc_6" hr_id="6" flag="done">

Attribute changes

The attribute changes are more complex. The range is empty, and is directly above the affected element (the one that has modified attributes). The <oxy-attributes> element contains details about multiple attribute changes, each stored in the <oxy-attributed-change> element.

<element>

  <oxy:oxy-range-start id="sc_3" hr_id="3"/>
  <oxy:oxy-range-end hr_id="3"/>

  <oxy:oxy-attributes href="#sc_3" hr_id="3">

     <oxy:oxy-attribute-change type="inserted" name="platform">
          <oxy:oxy-author>dan</oxy:oxy-author>
          <oxy:oxy-current-value>windows</oxy:oxy-current-value>
          <oxy:oxy-date>2018/03/15</oxy:oxy-date>
          <oxy:oxy-hour>10:05:04</oxy:oxy-hour>
          <oxy:oxy-tz>+02:00</oxy:oxy-tz>
     </oxy:oxy-attribute-change>
    ....
     <oxy:oxy-attribute-change type="removed" name="audience">
        ....    
     </oxy:oxy-attribute-change>
  </oxy:oxy-attributes>
...
</element>

Deletions

For a deletion, there are some elements that define the start and end of the deletion, and the highlighted text is wrapped in the <oxy-delete-hl> element.

   <oxy:oxy-range-start id="sc_2" hr_id="2"/>
   <oxy:oxy-delete-hl> This is a deleted text. </oxy:oxy-delete-hl>
   <oxy:oxy-range-end hr_id="2"/>

There is a structure that offers details about the deletion change, using the <oxy-delete> element. This is linked to the above deletion range by the same ID value:

   <oxy:oxy-delete href="#sc_2" hr_id="2">
       <oxy:oxy-author>dan</oxy:oxy-author>
       <oxy:oxy-content><image href="../img/ex.gif"></oxy:oxy-content>
       <oxy:oxy-date>2018/03/14</oxy:oxy-date>
       <oxy:oxy-hour>11:38:06</oxy:oxy-hour>
       <oxy:oxy-tz>+02:00</oxy:oxy-tz>
   </oxy:oxy-delete>

Colored Highlights

To show some text as highlighted with a background color:
  <oxy:oxy-color-hl color="rgba(140,255,140,50)">Some colored text.</oxy:oxy-color-hl>
Edit online

Comments and Tracked Changes - HTML Fragment

This section contains information about how each type of tracked change is structured in the merged map HTML file.

Insertions

For an insertion type of tracked change, the structure that defines the insertion details is inside a range (oxy-range-start to oxy-range-end), the inserted text is highlighted by a <span> element with the class oxy-insert-hl, and the details are stored in a <span> element with the oxy-insert class.

    <span class="oxy-range-start" id="sc_1" hr_id="1"/>

       <span class="oxy-insert" href="#sc_1" hr_id="1">
           <span class="oxy-author">dan</span>
           <span class="oxy-content">insert</span>
           <span class="oxy-date">2018/03/15</span>
           <span class="oxy-hour">09:38:29</span>
           <span class="oxy-tz">+02:00</span>
       </span>
       <span class="oxy-insert-hl">This is an insert!!</span>

    <span class="oxy-range-end" hr_id="1"/>

Comments

Similar to insertions, comments are defined in a range (oxy-range-start to oxy-range-end), the comment details in an element with the class oxy-comment, and the highlighted content is wrapped in the oxy-comment-hl element.

    <span class="oxy-range-start" id="sc_1" hr_id="1"/>
      
        <span class="oxy-comment" href="#sc_1" hr_id="1">
              <span class="oxy-author">dan</span>
              <span class="oxy-comment-text">This is a comment.</span>
              <span class="oxy-date">2018/03/15</span>
              <span class="oxy-hour">09:56:59</span>
              <span class="oxy-tz">+02:00</span>
        </span>
          
        <span class="oxy-comment-hl">The commented text.</span>
          
    <span class="oxy-range-end" hr_id="1"/>           
Note: Comments that are marked as done have a flag="done" attribute:
<span class="oxy-comment" href="#sc_6" hr_id="6" flag="done">

Attribute changes

The attribute changes are more complex. The range is empty, and is directly above the affected element (the one that has modified attributes). The element with the class oxy-attributes contains details about multiple attribute changes, each stored in an element with the class oxy-attribute-change.

<element>

  <span class="oxy-range-start" id="sc_3" hr_id="3"/>
  <span class="oxy-range-end" hr_id="3"/>

  <span class="oxy-attributes" href="#sc_3" hr_id="3">

     <span class="oxy-attribute-change" type="inserted" name="platform">
          <span class="oxy-author">dan</span>
          <span class="oxy-current-value">windows</span>
          <span class="oxy-date">2018/03/15</span>
          <span class="oxy-hour">10:05:04</span>
          <span class="oxy-tz">+02:00</span>
     </span>
    ....
     <span class="oxy-attribute-change" type="removed" name="audience">
        ....    
     </span>
  </span>
...
</element>

Deletions

For a deletion, there are some elements that define the start and end of the deletion, and the highlighted text is wrapped in an element with the class oxy-delete-hl.

   <span class="oxy-range-start" id="sc_2" hr_id="2"/>
   <span class="oxy-delete-hl"> This is a deleted text. </span>
   <span class="oxy-range-end" hr_id="2"/>

There is a structure that offers details about the deletion change, using the element with the class oxy-delete. This is linked to the above deletion range by the same ID value:

   <span class="oxy-delete" href="#sc_2" hr_id="2">
       <span class="oxy-author">dan</span>
       <span class="oxy-content"><image href="../img/ex.gif"></span>
       <span class="oxy-date">2018/03/14</span>
       <span class="oxy-hour">11:38:06</span>
       <span class="oxy-tz">+02:00</span>
   </span>

Colored Highlights

To show some text as highlighted with a background color:
  <span class="oxy-color-hl" color="rgba(140,255,140,50)">Some colored text.</span>
Edit online

Comments and Tracked Changes - Built-in CSS

The built-in CSS that controls the way tracked changes and comments are displayed is found in: [PLUGIN_DIR]css/print/p-side-notes.css.

Edit online

How to Style Changed or Commented Text

To style the highlighted text from the document content, use the <oxy-comment-hl> element (or <oxy-delete-hl>, <oxy-insert-hl>, respectively, by local name or class name):
oxy-comment-hl,
.oxy-comment-hl {
  color:magenta;
}
Note: The class name selector is useful when using the DITA Map PDF - based on HTML5 & CSS or DITA PDF - based on HTML5 & CSS transformation scenarios.

If you want to change the small labels that define the affected start and end ranges (they are a number formatted like: "[n] .. [/n]" where n is the number of the change), you can use the following selectors:

oxy-range-start:before,
.oxy-range-start:before {
  display:inline;
  content:'[' attr(hr_id) ']';
  color:red;
}
oxy-range-end:before,
.oxy-range-end:before {
  display:inline;
  content:'[/' attr(hr_id) ']';
  color:red;
}

Use display:none if you want to hide them.

If you want to change the background color of the comment footnote (assuming you set the show.changes.and.comments.as.pdf.sticky.notes transformation to no), add the following snippet in your customization CSS:

oxy-comment,
.oxy-comment {
  background-color:inherit;
  border: 2pt solid yellow;
}

Similarly, you can style the other footnotes for <oxy-attributes>, <oxy-delete>, and <oxy-insert> elements.

Edit online

How to Hide Tracked Change Footnotes

This topic is relevant if you have set the show.changes.and.comments.as.pdf.sticky.notes transformation parameter to no, and therefore the changes are shown as footnotes instead of PDF annotations.

In some cases, when your document contains a lot of tracked changes, you may need to hide the footnotes associated with the insertions, deletions, or attribute changes. Using the following example, the deletions and insertions are hidden, but the comments remain visible. In your customization CSS, add:
oxy-attributes,
oxy-delete,
oxy-insert{
  float:none;
  display:none;
}
Edit online

Troubleshooting

This section contains information about fixing various change tracking, highlights and comments publishing problems.

Edit online

Highlights are Spanning Unexpectedly to the End of the Page

Problem

Tracked changes and highlights span beyond what is expected.

Cause

If the change tracking insertions, comments, or highlights span over an area that is larger than expected, the markup that signals their end is missing.

Solution

To fix this, open the topic where the highlights start and check if the XML processing instructions that define the end of the highlighted interval are correct. The intervals are defined as follows:

For highlights:

<?oxy_custom_start type="oxy_content_highlight" color="140,255,140"?>
<?oxy_custom_end?>           

For comments:

<?oxy_comment_start author="dan" timestamp="20201102T092905+0200" comment="Test"?>
<?oxy_comment_end?>

For inserted text:

<?oxy_insert_start author="dan" timestamp="20201102T093034+0200"?>
<?oxy_insert_end?>

Make sure all the ending processing instructions are located before the root element end tag.