Menu
▾
▴
[Collective-checkins] r11554 - BookAnnotation/trunk
|
From: geojeff <svn...@pl...> - 2005-08-31 15:38:07
|
Author: geojeff Date: Wed Aug 31 11:28:20 2005 New Revision: 11554 Modified: BookAnnotation/trunk/README.txt Log: Updated README.txt to use stx and to show image link example. Modified: BookAnnotation/trunk/README.txt ============================================================================== --- BookAnnotation/trunk/README.txt (original) +++ BookAnnotation/trunk/README.txt Wed Aug 31 11:28:20 2005 @@ -1,65 +1,57 @@ -LICENSE +**LICENSE** - GPL: See BookAnnotation.py header. -CREDITS +**CREDITS** Javascript tooltips are done with Walter Zorn's tooltip library (http://www.walterzorn.com/tooltip/tooltip_e.htm). -AUTHORSHIP +**AUTHORSHIP** - initial coding: Jeff Pittman, http://www.geojeff.org -DESCRIPTION +**DESCRIPTION** -BookAnnotation 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 Charles Darwin's 'Voyage -of the Beagle': +'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: +<pre> Chapter 1 - Page 1 - 1: ----------------------------------------------------------------- - 2: ----------------------------------------------------------------- - 3: ----------------------------------------------------------------- - 4: ----------------------------------------------------------------- - 5: ----------------------------------------------------------------- - 6: ----------------------------------------------------------------- - 7: ----------------------------------------------------------------- - 8: ----------------------------------------------------------------- - 9: ----------------------------------------------------------------- -10: ----------------------------------------------------------------- -11: ----------------------------------------------------------------- -12: ----------------------------------------------------------------- -13: ----------------------------------------------------------------- -14: ----------------------------------------------------------------- -15: ----------------------------------------------------------------- -16: ----------------------------------------------------------------- -17: ----------------------------------------------------------------- -18: ----------------------------------------------------------------- -19: ------------------------------Beagle, a ten gun brig------------- -20: ----------------------------------------------------------------- -21: ----------------------------------------------------------------- -22: ----------------------------------------------------------------- -23: ----------------------------------------------------------------- -24: ----------------------------------------------------------------- -25: ----------------------------------------------------------------- -26: ----------Teneriffe---------------------------------------------- -27: ----------------------------------------------------------------- -28: ----------------------------------------------------------------- -29: ----------------------------------------------------------------- -30: ----------------------------------------------------------------- -31: ----------------------------------------------------------------- -32: -----------------------------------------Cape de Verd archipelago -33: ----------------------------------------------------------------- -34: ----------------------------------------------------------------- -35: ----------------------------------------------------------------- + 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: ---------------------------------------------- +</pre> -There are three annotated terms (or phrases) on this page. On the +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 @@ -67,86 +59,104 @@ Presentation choices include: - COMPLETE, all on one web page using a book page metaphor to show the +* 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. +* 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 +* 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 + +* 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 +* 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 '-') +* background character (default is '-') -- book_annotations, entered as comma-separated values on separate lines +* 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.) + - 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) + - 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) + - line (as an integer for the line on the page where the term occurs) - * left position (as an integer, for characters from left) + - left position (as an integer, for characters from left) - * term or phrase (as text; escape single or double quotes by - putting a \ in front) + - term or phrase (as text; escape single or double quotes by putting + a \ in front) - * annotation text (as text; also, watch for escaping quotes) + - annotation text (as text; also, watch for escaping quotes). Image tags + can be embedded within this field by escaping slashes and quotes: + <img src=\\\'200px-Ferdinand_Magellan.jpg\\\' width=\\\'200\\\'>. As + long as the image has been uploaded, it will be part of the tooltip. - * red, green, blue (each 0-255) [color isn't used presently, but - it could be to show terms - in different colors] - -REQUIREMENTS + - red, green, blue (each 0-255) [color isn't used presently, but it + could be to show terms in different colors] -- Archetypes (tested with Archetypes-1.3.2-final bundle) +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. -- Plone (tested with Plone-2.0.5) - -- wz_tooltip.js -- Walter Zorn's tooltip library - (http://www.walterzorn.com/tooltip/tooltip_e.htm). +This should also work well for regular textbooks. -PLATFORM NOTES +**REQUIREMENTS** -- So far, testing has only been done on Linux. +* Archetypes (tested with Archetypes-1.3.2-final bundle) -INSTALLATION +* Plone (tested with Plone-2.0.5) - 1. Put BookAnnotation in your Zope Products directory. +* 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). - 2. Restart Zope. +**PLATFORM NOTES** - 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. +So far, testing has only been done on Linux (RedHat 7.3, rhel 3.0, and Gentoo). -DERIVATIONS +**INSTALLATION** -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. +1. Put BookAnnotation in your Zope Products directory. -BUGS AND FEATURE REQUESTS +2. Restart Zope. -Please report bugs and feature requests to Jeff Pittman, who can be reached at -j...@ge.... Jeff is often on the #plone irc channel as geojeff. +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. + +**BUGS AND FEATURE REQUESTS** + +Please report bugs and feature requests to Jeff Pittman, who can be reached at +j...@ge.... Jeff is often on the #plone irc channel as geojeff. |