PDF Annotations

While certain XSL-FO processors support PDF annotations, the syntax and feature set differs. This page is attempt to offer some standardization in this field and encourage implementators to unify/broaden their interface. This would be beneficial for end users.

Real use cases:

1. Program listing as PDF annotations. Sometimes code lines are too long and have to be hyphenated so they fit in the limited page width. Because of hyphens this code cannot be copied/pasted to the target application directly. However, the original content of program listings can be placed besides the hyphenated program listings (e.g. in the margin) as Text PDF annotations - it can be opened and copied/pasted directly.
2. Slide notes. When XSL-FO is used for slides, it is handy to offer a 'trainer notes' feature. These can be in the form of Text PDF annotations. But when the content overflows to next pages, it is handy to repeat that annotation on every splitted page/slide.

For (1) it is necessary to control the annotation position. As in a double sided layout both inner and outer margins may differ, it would be handy to offer some function to retrieve the margin edge which could be just slightly manipulated.

For (2) it is necessary to bring any method for treating annotations as static-content, which repeats when the content overflows to next page.

Text annotations should support line breaks and inline formatting. Every line should be defined in some block element and formatting applied on inline tags (at least bold/italic styles).

Similarly to PDF outlines, the idea is to generate a specific annotation tree fragment to the final XSL-FO file. Despite there are several annotation types, in this proposal they are wrapped in more general element which controls the basic behaviour. Every specific type is equipped by applicable attribute sets. They can be derived from iText API.

Example of proposed syntax with some comments:

<?xml version="1.0" encoding="UTF-8"?>
<-\- part of XSL-FO file -->
<ppl:annotations xmlns:ppl="http://www.w3.org/community/ppl/">
  <!-\-
     Default attribute values:
        x = getX()
        y = getY()
        width = 0
        height = 0
        treatment = 'flow'
     
     Built-in functions for coords retrieval:
        getX() - returns the absolute left X coord of ID's block
        getY() - returns the absolute top Y coord of ID's block
        outer-edge() - returns the absolute X coord of outer margin
        inner-edge() - returns the absolute X coord of inner margin
     
     Treatment:
        flow - annotation is rendered only once
        static - annotation is rendered as it would be part of static content of the page-sequence which contains the ID's flow. 
                 When flow overflows to multiple pages, annotation is rendered on all of these pages.
  -->
  
  <!-\- 
     An available attribute set for every annotation type can be derived from this link:
     http://api.itextpdf.com/itext/com/itextpdf/text/pdf/PdfAnnotation.html
  -->
  
  <ppl:annotation for-id="id001" x="getX() + 10mm" y="getY() + 5mm" treatment="flow">
     <ppl:annotation-text title="Sample" open="false" icon="text">
        <ppl:block>Text supporting inline styling like <ppl:inline font-weight="bold"
              >bold</ppl:inline>.</ppl:block>
        <ppl:block>Another line.</ppl:block>
     </ppl:annotation-text>
  </ppl:annotation>

  <!-\- repeated text annotation when content overflows to next page -->
  <ppl:annotation for-id="id002" x="outer-edge() + 10mm" treatment="static">
     <ppl:annotation-text title="Sample">
        <ppl:block>Text.</ppl:block>
     </ppl:annotation-text>
  </ppl:annotation>

  <!-\- 
     link - for links additional functions would be handy (to get clickable region)     
  -->   
  <ppl:annotation for-id="id003">
     <ppl:annotation-link hightlight="none" width="block-width()" height="block-height()" namedDestination="id004">
     </ppl:annotation-link>
  </ppl:annotation>   
</ppl:annotations>