A quick guide to
PDF comments
in Prince

yellow sticky notes in any color

PDF documents can have comments, often shown as yellow sticky notes. The latest version of Prince will happily generate these, in any color you like. Prince is a HTML-to-PDF-via-CSS converter which offers advanced layout features so that you can create books from HTML.

To get started, we add a few lines of CSS to describe a basic comment:

htmlspan.sticker {
  -prince-pdf-annotation-type: text; 
  -prince-pdf-annotation-position: page-right;
  -prince-pdf-annotation-author: "The Editor";
  -prince-pdf-annotation-contents: "Are you sure?";
}

<p>This sentence deserves a <span class=sticker>comment</span>.

PDF viewers will show the comment in different ways, but all should display a yellow sticker with the name of the author («The Editor») and the comment («Are you sure?»). As you can tell from the property names, PDF comments are formally referred to as annotations.

(At the time of writing, the online PDF viewers built into browsers are not so good at presenting PDF comments. So, if you see something unexpected, try downloading the PDF files to your own computer and use a locally installed PDF viewer.)

Using data attributes

Rather the storing comments in CSS, they should be kept in HTML. Here's how to use data attributes for this:

htmlspan.comment {
  -prince-pdf-annotation-type: text; 
  -prince-pdf-annotation-position: page-right;
  -prince-pdf-annotation-author: attr(data-author);
  -prince-pdf-annotation-contents: attr(data-contents);
}

<p>This sentence deserves a <span class=comment data-author="The Editor" data-contents="Are you sure?">comment</span>.

Choose your icon

When creating text comments, you can choose between several icons:

htmlspan { -prince-pdf-annotation-type: text }

span.note { -prince-pdf-annotation-icon: note }
span.comment { -prince-pdf-annotation-icon: comment }
span.key { -prince-pdf-annotation-icon: key }
span.help { -prince-pdf-annotation-icon: help }
span.new-paragraph { -prince-pdf-annotation-icon: new-paragraph }
span.paragraph { -prince-pdf-annotation-icon: paragraph }
span.insert { -prince-pdf-annotation-icon: insert }

Colored icons

htmlspan { -prince-pdf-annotation-type: text }

span.note { -prince-pdf-annotation-icon: note }
span.comment { -prince-pdf-annotation-icon: comment }
span.key { -prince-pdf-annotation-icon: key }
span.help { -prince-pdf-annotation-icon: help }
span.new-paragraph { -prince-pdf-annotation-icon: new-paragraph }
span.paragraph { -prince-pdf-annotation-icon: paragraph }
span.insert { -prince-pdf-annotation-icon: insert }

Instead of icons

In the examples above, the PDF comments are attached to an icon; this is the result of setting the annotation type to text. Instead of an icon, you can also attach the comment to highlighted text, underlined text, wavy underlined text, and strike-through text:

htmlspan.hl { -prince-pdf-annotation-type: highlight }
span.ul { -prince-pdf-annotation-type: underline }
span.wy { -prince-pdf-annotation-type: wavy }
span.lt { -prince-pdf-annotation-type: line-through }

Colors

By default, these colors are used:

icons and highlights are yellow
underlines and squiggly underlines are green
strike-outs are red

This being CSS, you can obviously change the color. For example, you can make blue wavy lines:

htmlspan.comment {
  -prince-pdf-annotation-type: wavy; 
  -prince-pdf-annotation-color: blue;
}

Combining sources

htmlspan.comment {
  -prince-pdf-annotation-type: text; 
  -prince-pdf-annotation-position: page-right;
  -prince-pdf-annotation-author: attr(data-author);
  -prince-pdf-annotation-contents: attr(data-contents);
}

<p>This sentence deserves a <span class=comment data-author="The Editor" data-contents="Are you sure?">comment</span>.

Positioning icons: top, bottom, left, right

Comments can be positioned relative to their icons:

htmlspan.top { -prince-pdf-annotation-position: top }
span.bottom { -prince-pdf-annotation-position: bottom }
span.left { -prince-pdf-annotation-position: left }
span.right { -prince-pdf-annotation-position: right }

Positioning icons: page-top, page-bottom, page-left, page-right