Book Annotation

Project Description

Project resources

• Releases
• Contact address
• Project page

Book Annotation is a folderish Archetypes-based Plone/Zope product that produces web pages to show selected annotated terms for a book. Data for chapter, page, line, term, annotation text, etc. are entered as comma-separated data. Here's the basic result for a page, in this case for a few annotated terms on page 1 of Voyage of the Beagle by Charles Darwin:

Chapter 1
                                            Page 1
 1: ----------------------------------------------
 2: ----------------------------------------------
 3: ----------------------------------------------
 4: ----------------------------------------------
 5: ----------------------------------------------
 6: ----------------------------------------------
 7: ----------------------------------------------
 8: ----------------------------------------------
 9: -----------Beagle, a ten gun brig-------------
10: ----------------------------------------------
11: ----------------------------------------------
12: ----------------------------------------------
13: ----------------------------------------------
14: ----------------------------------------------
15: ----------------------------------------------
16: Teneriffe-------------------------------------
17: ----------------------------------------------
18: ----------------------------------------------
19: ----------------------------------------------
20: ----------------------------------------------
21: ----------------------------------------------
22: ----------------------Cape de Verd archipelago
23: ----------------------------------------------
24: ----------------------------------------------
25: ----------------------------------------------

There are three annotated terms (or phrases) on this page. On the actual web page, when you move your mouse over any of these three, you would see a pop-up tooltip with the annotation. You can control the number of lines on the page, the number of characters on a line, and the "background character," in this case a - is used.

Presentation choices include:

• COMPLETE, all on one web page using a book page metaphor to show the positions of the terms on the page and using tooltips to show the annotation text when a term is moused over.
• CHAPTERS, all pages in a given chapter are shown on a separate web page.
• PAGES, a separate web page for each book page.
• LISTING, all on one web page as a simple text listing

BookAnnotation takes input of the following items:

• lines per page (For Voyage of the Beagle it is 35, but it will vary from book to book. Use the maximum in your book, if there is variation.)
• characters per line (Count the characters on a number of lines, and use the maximum; This will work fine for most terms, as long as you use the actual text of the term or phrase, and don't add additional words)
• background character (default is -)
• book_annotations, entered as comma-separated values on separate lines with CSV data containing:
  • chapter (as text, so such things as Introduction and Appendix will work, in addition to Chapters 1, 2, 3, etc.)
  • page (as text, so such things as i, ii, iii, ... will work)
  • line (as an integer for the line on the page where the term occurs)
  • left position (as an integer, for characters from left)
  • term or phrase (as text; escape single or double quotes by putting a \ in front)
  • annotation text (as text; also, watch for escaping quotes)
  • red, green, blue (each 0-255) [color isn't used presently, but it could be to show terms in different colors]

As written, BookAnnotation would focus on a particular edition of a book. For example, Voyage of the Beagle will be an assigned reading for a college course, and the students will be told to purchase the exact edition at the bookstore (in this case a Barnes and Noble edition for about $10). That way when the student refers to a web page for a book page, the terms will be in the correct positions. This is central idea of one of the layout choices, shown above, wherein the reader can quickly locate the place in the text where the term or phrase occurs. A student could flip through the annotated pages before or after reading a chapter, they could pull up the web page for a particular book page when an unknown term is encountered, or they could flip through all the pages at once. Alternatively, they can view or print out the simple listing. However, one design objective is to offer a web interface that will be used instead of a dead-tree printout.

This should also work well for regular textbooks.

REQUIREMENTS

• Archetypes (tested with Archetypes-1.3.2-final bundle)
• Plone (tested with Plone-2.0.5)
• wz_tooltip.js -- Walter Zorn's tooltip library (http://www.walterzorn.com/tooltip/tooltip_e.htm). Put this file in the skins dir (Products/BookAnnotation/skins/BookAnnotation).

PLATFORM NOTES

So far, testing has only been done on Linux (RedHat 7.3, rhel 3.0, and Gentoo).

INSTALLATION

1. Put BookAnnotation in your Zope Products directory.
2. Restart Zope.
3. Install BookAnnotation into your Plone site using CMFQuickInstaller. (In Plone, select "plone setup", click on "Add/Remove Products" and install BookAnnotation.) You can also use the portal_quickinstaller tool from the ZMI to install the Product.

DERIVATIONS

Perhaps BookAnnotation could be modified for use in documenting a document for which the actual text is available. If that were the case, the same sort of annotation data would be gathered for terms and phrases, but instead of producing a "blank" page to show the terms or phrases, the actual text of the document could be shown in a subdued, but still readable color and the terms would be shown in highlight. Modifications could allow a system to markup to be shared by authors and/or editors.

TO DO

About images in tooltips

Walter Zorn's javascript library also does this. If images are set as allowed types, then a user (a user who can do img tags) could upload an image and add a tag for it within the text for an annotation, taking care to escape the quotes. Perhaps this will work...

BUGS AND FEATURE REQUESTS

Please report bugs and feature requests to Jeff Pittman, who can be reached at jeff@geojeff.org. Jeff is often on the #plone irc channel as geojeff.