- Requirements
- Users survey
- Vision
- Configuration
- Jython Dependencies
- Interface Specification for Helpers and Tools
- Preferences
- Using a JDOM document as a Swing Document
- Using Jython and Java



Users description

Project overview

Project requirements

Documentation requirements


1. Introduction

1.1. Purpose

The purpose of this document is to present the aims of the SPEdit project, what problems is addresses, what features it has, what are its requirements and what will the technical choices made.

1.2. Scope

This document is targeted at anybody who wants to have a first glimpse at what made the SPEdit originate. Actually saying "anybody" is a bit broad, as "anybody" should have some knowledge about the Swiss-Prot database.

2. Users description

2.1. User summary

The first thing to notice is that the SwissProt group embodies a certain number of subprojects, which are listed below:

  • HAMAP:
  • HPI:
  • Viruses:
  • Plants:

Two different kind of users can be identified for the SPEdit environment:

  • Reviewer:
    Reviews everything that is produced by the curators. They have to check first for the entry consistency with articles, and also check the syntax and orthograph of the flat file.

    Two types of entries are edited: quick entries take around 2 hours for review. The consistency check takes around 20% of the reviewing time, while the format checking takes the remaining 80%.

    The second type of entries are the more difficult ones, which involve a lot of reading. They can take a week to be annotated, compared to
  • quick entries the work is mainly focused on the consistency check, which takes up to 80% of the reviewing time, while the remaining 20% are spend in format* checking.
  • Curator:
    Transforms a TrEMBL database entry to a Swiss-Prot database entry by adding various type of information to the entry.

2.2. User environment

All users currently work under Windows, some of them are not that pleased of that system, mainly for stability and speed issues. Some would welcome any change in the system environment.

Curators and reviewers currently used macro-enhanced traditional text editors such as Brief and Crisp. These two editor are almost compatible and very close to each other- thought Brief is DOS-based and not so integrated into Windows, whereas Crisp is a fully Windows application.

Brief and Crisp alone would not be sufficient for the curator's every day work, so around 250 macros have been developed to fullfill a curator's needs.

3. Project overview

3.1. Project perspective

The SPEdit project is a stand alone desktop application made to replace the currently used curation environment which is composed by the BRIEF editor and a set of macros that help the annotation process.

The main conceptual difference remains in the ergonomical approach used: while Crisp and Brief are text-based editors enhanced with macros, the new curation environment will be fully graphical, and completely dedicated to the tasks involved in the annotation process.

A key feature of the editor is guidance , making sure that the most pertinent informations are given at the right time to the user.

3.1.1. Application architecture

SPEdit should be build on top of a flexible architecture that allows easy extensibility. In this respect, the chosen application framework should embody the following characteristics:

Core-level modularization: The application core should be configurable enough to fit any kind of XML editing needs, ranging from DocBook documents to more number-oriented formats, such as XML configuration file or tables.

Application-level modularization: Sitting on top of the application core resides the plug-ins which extend the behaviour of the application, providing new functionalities, new guidance, new coherence checks and new viewing possibilities.

User-level modularization: The last layer is the user-level provided by a macro API coupled to a scripting language. This one allows run-time easy configuration and customization of the editor.

3.1.2. Graphical user interface

An SPEdit document should look at the first glance quite close to an HTML document or to a Word document. This basically means that there should be no cryptic icons or diagrams, but simply a content-rich document wich content can be created/modified very easily.

3.1.3. Ergonomic aspects

Movement: Moving through the different elements in the document can be made naturally by using the mouse and selecting the element that we want to edit, by clicking on it. The behaviour of the component can be different depending on its type a paragraph will position the caret at the location where the click occurred, on the other hand a table will select the cell in which the user has clicked.

The other way is to use the keyboard. Navigation with keyboard can be made in two different «axes», the element-axis where the user will cycle through the different elements that form the document, and the component-axis, where the key press is interpreted (or not) by the component.

For example pressing the left key in a paragraph will move the caret one character left. On a table this will move to the next cell, and maybe on an image it may move to the next element too.

Insertion: The basic idea of insertion is that there is always in the document a blank text field surrounded by a coloured rectangle. By selecting this text field and pressing a key the user will transform this text field into a blank new element, or if there are more than one element possible at this place will pop-up a menu allowing to select which type of element to insert. Insertion can also be made by right clicking on this blank text field, which will also pop up the element selection menu

Expanding/Collapsing : The document can hide/show parts of its content, thus providing multiple "views" of its embedded information. Views can be also stored, allowing to quickly switch between one presentation and another.

Bookmarking: Easy navigation through the document is made possible throught bookmarking. Key locations in the document are stored by default in the bookmark list, and also custom bookmarks can be made by the curator either on the local document, or system-wide.

Deletion: Deletion would be made by right clicking the selected elements and by selecting the delete action.

Selection: Selecting elements in the document can be either made by choosing the select mouse tool and by clicking on different elements (maybe with the Shift/Ctrl) Selections may be saved (for later specific processing).

Keyboard philosophy: Basically any key press without a modifier key like Alt or Ctrl will be sent directly to the currently selected component. On the other hand if a modifier key is pressed then the application will handle the key press. For example this mechanism is used when moving through the different elements that constitute the document.

3.2. Summary of capabilities

Rich GUI. More ergonomic, allow multi-windowed environment. Access to the clipboard, integration with the system's web browser.
Text tagging. Allows to enable both human-readable and machine readable rich-content.
Plug-ins architecture. Functionalities can be added very easily, and have the benefit from using Java as a scripting language.
Guidance More effective, best learning curve, will guarantee that the curator will never waste time looking for she can do next.
Automatic processing Some things like the sequence checksum can be automatically calculated/modified.
XML Format Direct preview in a web browser, great flexibility and adaptation to future changes in the internal structure of the data.

3.3. Dependencies

The project will depend on the JDOM library which offer a simple and efficient way to manipulate XML document object from the Java language.

3.4. Licensing

As being developed at the SourceForge collaborative web site SPEdit and its subcomponents will be distributed under the GNU Lesser Public License.

4. Project requirements

4.1. System requirements

The application should run seamlessly under Unices, Windows and Mac OS. The application should be designed with particular care towards usability on a laptop. The application will run on the Java 1.3+ platform, using a Swing-based user interface. This choice has been made because Java is naturally cross-platform and features some patterns that can easily be reused in the context of this project.

4.2. Applicable standards

The Java, XML, XML-Schemas and XSLT standards can be applied.

4.3. Performance requirements

The curation environment should run on a 128MB, 400MHz+ processor.

5. Documentation requirements

5.1. User manual

The user manual should not present guidance for the curation process. Its content would be mapped to the editing process in a manner that allows to the user manual to be used both as a tutorial and as reference guide. It should not exceed 30 pages, should feature an index and a table of contents.

5.2. Online help

Online help should be quite short and only give information about what the user can do right now in the application as a classified list of application's features.