Annotations
This page contains information, discussions and research about the Evince annotations implementation.
Annotations? Why?
We all do annotations on paper when we read documents. We do annotations to allow us to locate important parts of the text when passing over pages. Our brain dispatch an alarm when our eyes look that fluorescent yellow mark over a lot of black characters.
Annotations on the screen should allow user to navigate fast over pages and mark important content in a distinguishable form.
PDF Annotations supports many types of annotation. Some look similar to things that we'd write on paper, like underlined words, or circled text. And some are for more professional uses like printer mark and watermarks.
Use Cases
Highlight: A non-english speaker reading some scientific paper written in English.
The user don't know the exact meaning of every word, but he could understand the global meaning. However, as a good language learner, he will later want to pass over the pages looking for that words that he didn't know. Tada! If words were marked they will be found faster.
Comment: Do you like this?
You wrote a paper and sent it to a friend for him to comment on. Your friend can add some notes to the document, next to the relevant phrases or pictures. He sends the document back and you can read his comments.
Underlining and more:
In general, preparing a paper for university consists of two parts:
1. the reading of the paper: sequentially, step-by-step, I try to understand the text and its argumentative structure. While doing this, I start underlining sentences that contain the essence of a paragraph and, even more important for me, I mark whole paragraphs and annote my own summary of them at the margins (which are often way too small on paper). This way I get a paper that shows me the important concepts of the text in the author’s own words (underlined) and my own words (marked paragraph, usually kind of bracketed, with annotation at the margins). So it would be cool if I could do this kind of marking/annotating (underlining vs. marking paragraphs) with Evince.
A special case is the reading of foreign texts: here I additionally mark unknown words (with a different type of underlining) and write the translation to the margin. It would be great to have the possibility to use different types of markup for words, lines, paragraphs ect. so I could easily distinguish which serves for what purpose.
2. the discussion of the paper in class: here I need to be able to find parts that are currently discussed in the paper. Ideally, a text is well structured and I can use headlines and subheadlines to follow the discussion. But in the real world, many papers are badly structured or not structured at all. So in this case I’d like to build an index by using something like bookmarks. Ideally those could be arranged in a hierarchical fashion. In a discussion, I could then jump to the relevant parts of the text, where I also find my annotations. Really cool would be the possibility to fade out the original text and just view the structure (of the text if it is good, otherwise the one derived from my bookmarks) with my annotations. This way it would be easy to remember a paper one has read long time ago.
Excerpt from this post
Use cases are welcome!
Research
Good start points:
Latest code from GNOME SoC 2007
http://google-summer-of-code-2007-gnome.googlecode.com/files/I%C3%B1igo_Mart%C3%ADnez.tar.gz
Discussion
NateNielsen: An idea: If you prefer not to have to write full 'save' support (incremental and otherwise) into poppler, you could do what Acrobat 7 does and save the annotations in a separate file. This makes collaborative commenting/annotating of a PDF document very simple. With Acrobat 7 all the annotations are written as small files in a predetermined directory. When anyone (on a network for instance) views the PDF document, all annotations are 'spliced' in.
Obviously this would not be a replacement for (the eventual) saving of the annotations in the PDF itself. But this may be a simpler first step. Again, just an idea. I haven't contributed to evince or libpopler, so I have no 'say' in the matter 
GilForcada: maybe the Tomboy infrastructure can fit well here and the dictionary from gnome-utils its useful too (for the usecase of non-english speakers)
Gabriel Wicke: +1 for using separate files in general- this way you can still pass unchanged pdfs around, share annotations separately (for example for course work). It is possible to efficiently revision-control and possibly combine them. It is possible to annotate any file format supported this way (ps, djvu, tiff, dvi,..).
As Xournal implements this already it might be useful to look at or reuse some of its code. Rendering of strokes, underlines and highlighters is really smooth. It stores its data in compressed xml files (*.pdf.xoj), typically ~70kb for a fully hand-written page. The code is gtk/glib-based, pdf backgrounds are rendered as gdk-pixbufs through pdftoppm.
Xournal can also export the annotations to a new, combined pdf by overlaying/extending the original pdf with some more vector data. It is possible to view these exported, annotated pdfs with any pdf viewer. Afaik it does not use the pdf annotation spec. -> http://xournal.sourceforge.net/, apt-get install xournal
There is also some support for producing annotations with Inkscape by importing a bitmap background. The editing side is very strong, and it would be possible to leverage other SVG tools. Embedding typed text is also already supported, the Xournal format lacks this. File size for hand-drawn pages is similar to the one with Xournal- typically sub-100k. See https://help.ubuntu.com/community/Wacom for help on Inkscape drawing.
[KarlHeg]: (some of this should be moved to other pages as I explore this Wiki.) For separate-file bookmark outlines and annotations, the file should be identified by SHA1 hash rather than by file system path, so that when the file is moved the outline and annotations remain associated with it. There should be a fallback method of document identification also, based on document content in some way such that changes to the document don't prevent it from realizing that it's the same document with changes. I'm not sure how that should work yet. It needs to look at more than one chunk of the document and to mainly ignore formatting, so perhaps something that works only with the textual content and sees when it's mostly the same as a document that "evince" has already seen and has bookmarks or annotations for. That feature implies that when a document changes it should offer a chance for the user to verify that the annotations are still on the right pages (they should be associated with some sort of document context) and that the bookmark outline still points to the right pages. If a chapter or section was added, if there's not an automatic way for it to know that, the user should be able to easily and quickly adjust a group of bookmarks, like say "the new chapter is 10 pages, so add 10 to all bookmark page targets from bookmark "XXX" to the end.
I would like the UI to allow me to add bookmarks at will, by pointing to a spot in the document and adding a bookmark outline link to it that can be kept in a separate file OR inserted into the PDF itself. (It should obviously have the capability to add the separate file ones to the PDF, and also perhaps to a PS via DSC-like comments... maybe those can work like the PDF document structuring features do.) I would like to be able to take a PDF without bookmarks, and tell "evince" that "The TOC starts on page c and ends on page f. Use built-in regular expression number 2 to parse the TOC, and use the parsed information to create a bookmark outline hierarchy." If there's no built-in regexp that works right, I should be able to specify one. It should operate on a textual representation of the document's TOC... I'm not sure if that text representation should include indenting or not, but certainly I should not have to try and form an expression that looks around the PDF/PS language markup -- it ought to see only lines of text as my eyes do, obviously.
Perhaps there should be several types of bookmarks, so that ones gleaned from the TOC or backlinked from the Index (clickable spots and/or an outline view in the sidebar?) can be differentiated from your own bookmarks which are more like the card-stock ones with bookstore ads on them you use to keep track of where you are in a book... or really more like those nice ribbons attached to the binding of finer hardbacks. There should not be a fixed set of bookmark types, though there should be some pre-defined and reserved type tags. I might want to bookmark a paragraph, an annotation, a page or paragraph range, or an illustration. I might want that bookmark to be associated with part or all of some external document, like my academic research notes on the particular paper the bookmark is on. An external application should be able to ask "evince" to jump to a bookmark too, so there needs to be a textual representation of the bookmark to call it by; a URI of some sort. I don't think "evince" should try to take on the role of note-taking editor -- annotations are not designed for that, it's too much functionality outside the scope of a document viewer ("reader"? text to speech? for reading/parsing mathematical expressions, see Mathtalk and AsTeR.) and that people taking notes for academic research will want their notes for any particular paper all in one place near the document they are writing. It would be great to be able to link from the paper to the notes and back.
I also want quick links to TOC, Appendix, and the Index along with easy UI for jumping there. DEC SRC had a project they called "Digital Paper", and there they implemented, in Modula 3, a program called "lecturn" that was a fairly decent document reader. It's UI had some great features and keybindings for navigating a document. You'd push "i" to jump to the Index, "c" to jump to the TOC, and simply type a page number to jump to a page. It had way to edit those locations for a document that did not yet contain metadata for that. You could tell it what physical page was logical page 1, what physical page was the start of the TOC and Index, etc. Reading in "lecturn" is very natural -- almost like reading a paper book, only page-flipping is much faster, like having index-tabs on the pages the way "A" students do with their textbooks. Another nifty feature of "lecturn" is an eye-guide line that it draws when you scroll the document. After experiencing it, I wrote a feature request to the "gv" maintainer, who quickly added it. When you scroll down, a thin line is drawn across the document where the bottom of the window used to be. It's there for long enough for you to move your eyes (or the mouse pointer) up to that location, and then it's erased.
DEC SRC Virtual Paper "lecturn" documents were created by churning out fixed-resolution bitmaps from a Postscript file, or from scanned documents. When going from Postscript, it would grab the text and word bounding-boxes during the processing, and that information was stored in the document, making it searchable and highlight-and-pasteable. For scanned documents, on some platforms, it supported OCR. That might be useful for scanned DjVu or PDF, perhaps...? -- KarlHeg.
BenjaminPerez: I'm equal with the idea to work with Tomboy, I have this idea integration evince-tomboy, was an idea that it had for the SoC. is even necessary to extend but this idea.
HeikkiHenriksen: Please remember that most people don't use annotations actively. They receive pdf-documents with annotations created in Adobe and wonder what those yellow speech balloons in evince are. They can't read the comments and are annoyed because the balloons still appear in presentation-mode.
AndreaZanni: Guys, I don't know if this is the right place to ask, but I would like to know if there are some news about annotations in Evince. Personally, I really would like to have few important tools, as highlighting, underlining, commenting. I have few advices, if you want them (I just studied a bit the field of annotation for a research proposal). If this is the wrong place, just rollback (but answer me).
CarlosGarciaCampos: http://carlosgc.linups.org/gnome/evince-2-26-without-annots.html
AndreaZanni: thank you. I will follow this project, and see if I can help (I'm not a developer, but I just studied some theoretical research on annotation, maybe I can hel with design).