sporadic work in progress. last updated on 2016-02-10 (BREAKS EARLIER VERSION, see below)

WARNING: if you have used this before, and are planning to update, please backup your highlights database before updating

this plugin is NOT pre-packaged and ready to use. You will need to setup some dependencies (see below)

There are 2 main issues we care about here, addressed in headings below

1. importing, i.e. reading annotations made elsewhere.
2. editing, i.e. displaying and editing annotations in calibre’s ebook-viewer program. this is doable now. read below for details. notes are stored into an sqlite database using the okfn/annotator API and thus their JSON format.

• sqlalchemy (currently working with 0.9.8)

installable via pip install sqlalchemy; due to PATH HACK below, we’re assuming a system install where you know the inclusion path for both libraries

download and extract sqlalchemy, and

mv SQLAlchemy-*/lib/sqlalchemy calibre/lib/python2.7/site-packages

NOTE: if you have problems installing over an existing =Viewer Annotation Plugin.zip= in your calibre plugins directory, try deleting that zip file first

1. ensure you have a working development environment set up (basically, ensure you can run calibre-customize)
2. clone this repo
3. edit the PATH HACK ViewerAnnotationPlugin/annotator_model.py so calibre is able to see your local install of sqlalchemy. It is currently hard-coded to search in /usr/local/lib/python2.7/dist-packages. There’s probably a way to make this self-contained; see discussion here but it’s not currently a priority.
4. in your terminal/command line program, navigate to the ViewerAnnotationPlugin directory and run calibre-customize -b . to install the plugin. If successful your ebook-viewer should incorporate the annotations. By default it will create a sqlite database ebook-viewer-annotation.db into your home directory.

work in progress; see nwapp branch for progress on importing text from kindle notes

The base plugin code is loosely taken from user interface plugin, although the viewer plugin is slightly different. refer to the Viewer plugins section in the calibre API documentation. Other exploratory notes on interacting with calibre proper may be found in the doc/devlog.

To play with this code, edit the code in the ViewerAnnotationPlugin directory, then run

calibre-customize -b . && ebook-viewer $PATH_TO_EPUB

and it should launch the viewer with the changes applied.

We generally follow the format from Annotator

A sample Annotation structure is like:

{
  "id": 42,                                  // INTEGER NOT NULL PRIMARY KEY
  "created": "2014-11-02 12:19:13.000000",   // DATETIME DEFAULT NOW
  "updated": "2014-11-02 12:19:13.000000",   // DATETIME DEFAULT NOW
  
  "title": "The title of an exemplary book", // TEXT, title of book in Calibre
  "text": "A note I wrote",                  // TEXT, content of annotation
  "quote": "The text actually said this, since I quoted it.", // TEXT, the annotated text (added by frontend)
  "uri": "epub://part0036.html",             // TEXT, URI of annotated document (added by frontend)

  "user": "yousir",
  
  // these are populated run-time by backref via the `range` table
  "ranges": [                                // list of ranges covered by annotation (usually only one entry)
    {
      "start": "/p[69]/span/span",           // (relative) XPath to start element
      "end": "/p[70]/span/span",             // (relative) XPath to end element
      "startOffset": 23,                     // character offset within start element
      "endOffset": 120                       // character offset within end element
    }
  ]
}

A sample Range structure is like:

{
  "id": 2,                               // INTEGER NOT NULL PRIMARY KEY
  "start": "/p[69]/span/span",           // VARCHAR(255), (relative) XPath to start element
  "end": "/p[70]/span/span",             // VARCHAR(255), (relative) XPath to end element
  "startOffset": 23,                     // INTEGER, character offset within start element
  "endOffset": 120,                      // INTEGER, character offset within end element
  
  "annotation_id": 42                    // INTEGER FOREIGN KEY(annotation.id)
}

The Consumer model is defined (inherited from the older reference implementation) but is not used.

current code is hard-coded to expect annotator-full.1.2.7 for javascript/css. For a different version:

1. visit https://github.com/okfn/annotator/downloads/
2. if you’ve unzipped e.g. annotator-full.1.2.7.zip, you should get a directory annotator-full.1.2.7/ with a .js and a .css file inside it. Move this directory into the ViewerAnnotationPlugin directory.
3. edit ViewerAnnotationPlugin/__init__.py and find the load_javascript and run_javascript sections and make sure the paths there correspond to your extracted annotator js/css files.

see store.coffee; store.js is derived from coffee --compile store.coffee then moved into ViewerAnnotationPlugin

The most recent update (2016-02) is not compatible with all updates prior to 2016. However, the data model is mostly the same.

• sometimes editing an annotation raises a UnicodeError (could be related to imported highlights)
• annotation stops working with changing flow mode (ref whacked#2)

If you actually need to migrate, see migrate.sh which tries to convert the tables to the newer data model.

In particular, quote is now the default Annotation field to store the highlighted text; text is for comments. timestamp is superceded by updated and created.

• either the js file inclusion or css style injection or both cause long pauses in the reader when navigating between epub chapter boundaries