DITA includes the <draft-comment> element which many writers use to add comments for their Subject Matter Experts (SMEs). However, when a SME is reviewing a PDF in a PDF reader, there is no easy way to call the SMEs attention to the <draft-comment> elements. It is easy to add special formatting to make the <draft-comment> elements stand out on the page, but the SME must still page through the PDF to find them all. Wouldn’t it be handy to have a way to automatically generate a list of these <draft-comment> elements that the PDF reader can display?
Here is a fairly easy way to do just that:
Note: This process depends on an Antenna House extension – it will not work for FOP or XEP. In addition, the screen shots in this post are from Adobe Acrobat Reader 2019. Other PDF readers or other versions of Acrobat Reader might display the annotations differently.
PDF readers can already display a list of PDF annotations—the sticky notes, comments, and other items that can be added within the PDF reader when commenting on a PDF. You can leverage this capability to create a PDF annotation for every <draft-comment> in a PDF. This annotation can be empty, since all you really want to do is provide a way for the SME to quickly view the corresponding <draft-comment>—when they click an annotation in the Comments list, they go right to the <draft-comment>.
The Antenna House documentation explains that the axf:annotation extension creates PDF annotations. It also explains the various formatting options available for the annotation. These options can be used to specify the type of annotation (which is required) but many other properties, such as border and font properties, color, the initial state (open or closed), the author, and more.
Start simply by adding a yellow sticky note annotation to each <draft-comment>.
Create the Annotations
As you might suspect, because you are adding the annotation to <draft-comment>, it is necessary to override the template that processes <draft-comment> elements in your own plugin. In the org.dita.pdf2 plugin in DITA OT versions 2.5.4 and later, this template is found in the topic.xsl file. In earlier versions of the DITA OT, it is found in the commons.xsl file.
The first line of the template looks like this:
[custom_font font_family=’Courier New’ font_size=’19’ line_height=’26’ font_style=’none’ text_align=’left’ font_weight=’300′ color=” background_color=” text_decoration=’none’ text_shadow=’no’ padding=’0px’ margin=’0px’] <xsl:template match=”*[contains(@class,’ topic/draft-comment ‘)]”> [/custom_font]
If you have not already included this template in your own plugin, go ahead and copy it in.
Next, add the following line to the xsl:stylesheet declaration of the XSL file that the template is in:
[custom_font font_family=’Courier New’ font_size=’19’ line_height=’26’ font_style=’none’ text_align=’left’ font_weight=’300′ color=” background_color=” text_decoration=’none’ text_shadow=’no’ padding=’0px’ margin=’0px’] xmlns:axf=http://www.antennahouse.com/names/XSL/Extensions [/custom_font]
This is necessary because the Antenna House annotation extensions, in this next example, include the axf:namespace, which you must declare before using.
Next, add the highlighted text to the template:
These lines create a new block and format that block as a PDF annotation. In this case, the annotation is a text annotation; it is not open initially. The annotation contains the text “Review,” has a yellow icon, and it is offset from the text by 20mm.
The result of these changes is something like this:
More importantly, the annotation is now present in the Adobe Acrobat Comments list:
SMEs can now display that list and quickly move from one <draft-comment> to the next without having to page through the PDF.
Note: PDF readers other than Adobe Acrobat might not display an annotation icon. However, the annotation is still present in the Comments list (or that reader’s equivalent) in all the common PDF readers.
Indicate the Disposition in the Annotations
The <draft-comment> element includes a disposition attribute used to indicate the status of the <draft-comment>. For example, when a <draft-comment> has been addressed, it can either be deleted, or, if you prefer to keep a record if it, have @disposition to something like “complete.” The value of @disposition can then be used to control how the annotation is created in the PDF.
To make this happen, use xsl:choose to test for the value of @disposition and format the annotation accordingly. Here, <draft-comment> elements with a disposition of “complete” produce annotations that are green and contain the text “Complete.” All other <draft-comment> elements produce annotations that are yellow and contain the text “Please review.”
In Acrobat Reader, it looks like this:
Exclude Annotations Based on the Disposition
Alternatively, you could choose to hide annotations for <draft-comment> elements with a “complete” disposition:
Display the Assigned SME
In a case with a large PDF going out to several SMEs at once, you may want to point each to specific comments. Unfortunately, there is no SME attribute for <draft-comment> but there is an author attribute. It might not be very helpful to SMEs to know who the author of the <draft-comment> is but it is helpful to them to know which <draft-comment> elements they need to pay attention to.
Repurpose @author if you don’t need to use it to record the <draft-comment> element’s actual author. (Some might call this tag abuse, but just think of it as tag expansion.)
In any case, to do this, take the value of @author and use it as the annotation’s contents. First, create a variable that has the value of @author as its value, then specify the value of the SME variable as the value of @author:
Here is the result. BilalR can scan the Comments list and address only items assigned to him:
If you do need to use the author element for your author, or want to avoid any suggestion of tag abuse, use the <draft-comment> element’s otherprops attribute or specialize <draft-comment> to create your own element with an expanded list of attributes.
Summary
These are just a few of the things you can do with Antenna House’s annotation extensions. Experiment and see what else you can come up with!
