Scheherazade v${VERSION} by David K. Elson
Copyright 2005-2011 David K. Elson

A semantic annotation tool for narratives.



-=-=-=-=-=-=-=-
USAGE

If you are running the JAR file directly from the command line, be
sure to provide at least 1024M of memory and 128MB of PermGen space:

> java -XX:PermSize=128M -Xmx1024M -Xms1024M -jar scheherazade-${VERSION}.jar

If you are running from the Windows build, first "extract all files"
(do not attempt to run Scheherazade from a "preview" of the zip file's
contents -- have Windows unpack the zip).  Click the provided batch
file (scheherazade-${VERSION}.BAT).  This will launch Scheherazade
with the correct settings.

If you are running Windows 7 on a 64 bit computer, run the provided 64
bit launcher (scheherazade-${VERSION}-64bit.BAT) instead.

If you are running from the Mac OS X build, simply double-click the
application and it will run.

-=-=-=-=-=-=-=- 
Release History
## 0.33 (2011-03-03)
-- Bug fix that eliminated some adjective frames by accident.  

## 0.32 (2011-03-02)
-- Addition of about 9,000 new adjective frames.  
-- Change in the way the knowledge base encodes adjectives.  Due to
   this change, some files created with versions from 0.04 to 0.31 may
   not load correctly.  If this is the case with your saved files, run
   the files through the included Perl script updateAdjectiveIDs.pl
   which will update the adjecive references embedded in your file.

-- Bug fixes.

## 0.31 (2011-03-01)
-- Bug fix.

## 0.30 (2011-03-01)
-- Fix for bug that prevented certain files from loading.
-- New Interpretative nodes now start life positioned wherever
   the middle of current view of the canvas is, instead of at the
   top of the canvas. (At the moment the view still snaps back
   to the last selected node, so click on bare canvas to de-select
   all nodes first.)

## 0.29 (2011-02-22)
-- Source-story links can now be edited.  In Timeline view, press the
   Edit button for the proposition whose linked span of source text
   you wish to alter.  Then, highlight the new span in the source text
   pane.  The link will then update.  Click the banner button for the
   unchanged proposition to cancel back out of edit mode.

## 0.28 (2011-02-21)
-- Scheherazade now shuts down automatically if an error happens
   during the loading of a saved file.  This is to avoid the
   possibiltiy of re-saving the partially loaded file, which could
   lead to data loss.
-- External text files are now processed more carefully to avoid 
   alignment problems when loading saved files.
-- Highlighting is now global across Timeline and Interpretative 
   views.  Clicking on an interpretative-screen source box,
   for instance, will highlight the corresponding passage in the
   top-right Source Text view, and have the Timeline flip to the
   corresponding Story Point.  Clicking on an action in the Timeline
   will select the corresponding node in the Interpretative panel,
   and show all the pursuant activations.

## 0.27 (2011-02-21)
-- Bug fix.

## 0.26 (2011-02-18)
-- No longer allows content within an interpretative "core" goal.
-- (API only) Interpretative node reattachment recommand (for moving
   nodes in and out of "agency boxes."

## 0.25 (2011-02-17)
-- Bug fixes.

## 0.24 (2011-02-15)
-- Bug fix.

## 0.23 (2011-02-14)
-- Another Change to the way actualizations propagate through certain
   graph topologies (BECAUSE arc).
-- Bug fix.

## 0.22 (2011-02-11)
-- Revamp of Core Goals.
-- Changes to the way actualizations propagate through certain
   graph topologies.
-- Bug fixes.

## 0.21 (2011-02-11)
-- Actualizations/ceasings are now computed by Scheherazade and
   the results are shown in the interface by color coding interpretative
   nodes.  No longer do annotators have to trace actualization paths
   themselves.
-- Implements model feature that "because" arcs are not valid conduits
   for goal draining.
-- Implements model feature that beliefs do not have to drain.

## 0.20 (2011-01-04)
-- UI improvements.
-- Bug fixes.

## 0.19 (2010-12-27)
-- Bug fix.

## 0.18 (2010-12-14)
-- Bug fix.

## 0.17 (2010-12-13)
-- Bug fixes.

## 0.16 (2010-12-11)
-- Bug fixes.

## 0.15 (2010-12-09)
-- Bug fixes.

## 0.14 (2010-12-07)
-- Noun groups are overhauled.  You can now add members to a group
   without manually selecting a noun class to which they belong.  When
   you invoke the group, the system will verbalize the members as a
   list.  The result is that you can describe characters doing things
   in tandem: "The eagle and the tortoise flew."
-- "The air" is now a basic, given location type.  (When invoked, it
   is verbalized as "the air," not "an air."  This is intended for use
   in weather descriptions: "the air is hot."

## 0.13 (2010-12-05)
-- New weather-related verb frames added (e.g., "it rains").
-- Qualities can now be used in as arguments for a much wider range of
   predicates.
-- Bug fix that prevented proper loading of saved encodings that used
   a new feature.

## 0.12 (2010-12-04)
-- Addition of two new arcs, "because" and "implies," and an adjustment
   of the annotation guidelines to accommodate them.
-- UI and verbalization bug fixes.

## 0.11 (2010-11-29)
-- Fix of a Critical bug that prevented proper loading of saved
   encodings that used certain features.

## 0.10 (2010-11-28)
-- Added some missing KB elements
-- New "ceases" interpretative-level arc to oppose "actualizes"
-- Better enforcement of interpretative linking rules ("provides for"
   and "damages" will only link to core goals).
-- Verbalization bug fix
   

## 0.09 (2010-11-23)
-- Scheherazade will now let users load in a custom text file to
   encode.  Users are no longer limited to Aesop's fables or an
   original story.
-- The data file format ("VGL") has been rewritten.  It now begins
   with an XML structure with information about the encoding.  The
   original story is then included inline.  (Don't alter the copy of
   the source text found in this file, or the alignments to the
   encoded version will go askew.)
-- Scheherazade now includes a legacy file reader for the old version
   of the VGL file (0.01 through 0.08).  Users are encouraged to load
   their current VGL files and resave them in the new format.
-- Source text selection now snaps to the nearest whole word.
-- Now includes a separate source file, "ScheherazadeDemo.java", that
   demonstrates how developers can use the Scheherazade API directly
   (bypassing the graphical interface).  The API provides access to
   every GUI feature; the GUI uses the same API exclusively.
-- Now includes Javadoc documentation so developers can write
   extensions against Scheherazade's API.


## 0.08 (2010-11-22)
-- Gerunds are now supported as behaviors.  "<A young man pursuing
   love> is admirable."
-- Much improved verbalization of goal, plan and obligation boxes in
   Interpretative mode (including redundancy avoidance).
-- Launcher for 64 bit Windows now included.
-- Bundle size reduced by about 50% to 12 MB.
-- Organizations and social groups added to knowledge base as
   potential characters.  Social gatherings added as Behaviors.
-- Fix for a bug that prevented loading of files with certain types of
   content.
-- Now built against Java 1.5 (rather than 1.6) for compatibility with
   older machines
-- Scheherazade now lives in a window with the usual OS controls
   (maximize, minimize, resize) rather than forcing itself into full
   screen, non-resizable mode.
-- Bug fixes


## 0.07 (2010-11-16)
-- Verbalizations are now generated for "agency boxes" in the
   interpretative screen.  They will illustrate what the goals, plans
   or obligations are, and how they influence other elements.
-- Knowledge base enhancements.
-- UI adjusted for ease of use.  Most notably, the character selector
   dropdown in timeline screen is eliminated.  Agents must be selected
   as part of the predicate construction form.
-- Bug fixes.


## 0.06 (2010-11-10)
-- Ground-up reorganization of knowledge base to improve efficiency
   and coverage.  This includes abstraction of noun types to allow for
   additional types.
-- Introduction of two new noun types, Behavior (for activities like
   "a dance") and Quality (for attributes like "intelligence" or
   "hue").
-- Major new feature: Interpretative annotation.  Expansion of story
   graph data structure to include elements of character agency:
   goals, beliefs and obligations.  Canvas-like interface that allows
   encoders to "draw" story information that is implied but never
   stated -- and connect that information to the elements that are
   stated.
-- Support for markup of source text (encoders can now indicate what
   span of source text is associated with each encoded proposition)
-- Many bug fixes


## 0.05b (2009-01-07)
-- Knowledge base greatly enlarged:
   Now over 93K object frames, including 47K prop types, 15K character species
      Proper nouns now included
   Now over 30K verb frames, including "HOW" frames
   Over 3K new adverb frames
   Memory usage reduced further (still ~350MB required in heap)
-- "Connective" adverbs frames for inferential links within the story
-- Object frames can now be nested (e.g., groups of groups of objects)
-- Root types can now be selected ("a character")
-- Abstract objects allow your characters to speak abstractly ("if a mouse...")
-- Tense and aspect conjugation improved in alternate timelines  
-- Properties can now be negated ("he didn't begin to feel...")


## 0.05a (2008-12-31)
-- Memory usage greatly reduced (41%).  Can now comfortably run in a
   512M heap (typically uses ~350 MB).  [Note: Current version
   requires 1024M due to additional knowledge.]
-- Speed optimizations; no longer slows significantly after extended use
-- Searching is now much faster as well
-- Alternate timelines expanded to handle many combinations of tense, aspect
   -- Use "attachment points" to create past, future tense
      The attachment point represents "the present" when the timeline is used
   -- Use "IF buttons" to create different aspects
-- Alternate timelines now invoked in thousands of new action frames
-- Greater backwards compatibility for saved story files
-- Creating highly nested predicates now easier when one runs out of space.
   Clicking the intermediate "banners" to hide the completed parts of the
   predicate and leave more room for inner frames
-- GUI changes to lower the learning curve
-- Miscellaneous bug fixes


## 0.04 (2008-11-07)
-- Major new version
-- Search capability for selecting noun and verb types
-- Over 40,000 new available noun types
-- Over 27,000 new available verb frames (action types)
-- Over 14,000 new available adjective frames (condition types)
-- New feature: Modifiers
   - Indicate causal relationships between events
-- Actions can now be negated ("he didn't...")
-- Objects can now be arranged into groups
-- Multiple timelines now supported, can be used for many modes
   - Imaginary events
   - Obligated events
   - Fears
   - Hopes
   - Plans
-- Generation component has more sophisticated grammar
-- Many smaller improvements to interface and underlying model
 
## 0.03 (2008-02-06)
-- Bug fixes

## 0.02 (2008-02-05)
-- Can now edit actions and properties
-- Redesigned, greatly simplified GUI 
-- Attributes (properties as a part of an element's definition)
-- Expanded Aesop knowledge base
-- Many bug fixes

## 0.01 (2007-11-09)
-- Initial release

-=-=-=-=-=-=-=-

Known Bugs

-- Performance lags in alternate timelines due to re-indexing
-- Memory usage increases over time
-- Certain grammatical constructions still missing
-- Search performance will be improved
-- Help content needs to be expanded
-- Crash occurs when attempting circular group membership (group A
   includes group B, which is edited to include group A); this needs
   to be anticipated and not presented as an option.

-=-=-=-=-=-=-=-

Credits

-- Marshall Fox contributed to the help system
-- All other design and coding by David
-- Thanks to all our formative evaluators and collection experiment subjects

-=-=-=-=-=-=-=-

Legal

This software is an intermediate product of research in progress.  It
comes with ABSOLUTELY NO WARRANTY.

It is licensed at this time for demonstration purposes only.  All
commercial or research uses, including redistributing, decompiling,
linking, transferring, creating derivative works, conducting
experiments and other uses are prohibited.

(It's getting closer to a stable release, but if you'd like to use it
soon for research purposes, do contact us and we can work something
out: delson@cs.columbia.edu.)

-=-=-=-=-=-=-=-

WordNet license

WordNet Release 3.0

This software and database is being provided to you, the LICENSEE, by  
Princeton University under the following license.  By obtaining, using  
and/or copying this software and database, you agree that you have  
read, understood, and will comply with these terms and conditions.:  
  
Permission to use, copy, modify and distribute this software and  
database and its documentation for any purpose and without fee or  
royalty is hereby granted, provided that you agree to comply with  
the following copyright notice and statements, including the disclaimer,  
and that the same appear on ALL copies of the software, database and  
documentation, including modifications that you make for internal  
use or for distribution.  
  
WordNet 3.0 Copyright 2006 by Princeton University.  All rights reserved.  
  
THIS SOFTWARE AND DATABASE IS PROVIDED "AS IS" AND PRINCETON  
UNIVERSITY MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR  
IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PRINCETON  
UNIVERSITY MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANT-  
ABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE  
OF THE LICENSED SOFTWARE, DATABASE OR DOCUMENTATION WILL NOT  
INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR  
OTHER RIGHTS.  
  
The name of Princeton University or Princeton may not be used in  
advertising or publicity pertaining to distribution of the software  
and/or database.  Title to copyright in this software, database and  
any associated documentation shall at all times remain with  
Princeton University and LICENSEE agrees to preserve same.  

WordNet 3.0  Princeton University 2006

-=-=-=-=-=-=-=-

VerbNet license

This software and database is being provided to you, the LICENSEE, by
University of Colorado under the following license.  By obtaining, using
and/or copying this software and database, you agree that you have
read, understood, and will comply with these terms and conditions.:

Permission to use, copy, modify and distribute this software and
database and its documentation for any purpose and without fee or
royalty is hereby granted, provided that you agree to comply with
the following copyright notice and statements, including the disclaimer,
and that the same appear on ALL copies of the software, database and
documentation, including modifications that you make for internal
use or for distribution.

VerbNet 2.3 Copyright 2006 by University of Colorado.  All rights reserved.

THIS SOFTWARE AND DATABASE IS PROVIDED "AS IS" AND THE UNIVERSITY 
OF COLORADO  MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, UNIVERSITY 
OF COLORADO MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANT-
ABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE
OF THE LICENSED SOFTWARE, DATABASE OR DOCUMENTATION WILL NOT
INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR
OTHER RIGHTS.

The name of University of Colorado or CU may not be used in
advertising or publicity pertaining to distribution of the software
and/or database.  Title to copyright in this software, database and
any associated documentation shall at all times remain with
University of Colorado and LICENSEE agrees to preserve same. 


Please reference the following document in any description of 
applications based on VerbNet 2.3: 

Karin Kipper, Anna Korhonen, Neville Ryant, and Martha Palmer.  
Extensive Classifications of English verbs.   
Proceedings of the 12th EURALEX International Congress.  Turin, Italy. 
September, 2006.


-=-=-=-=-=-=-=-=-

