-
the Pavlov site -
PDFPDF version

Pavlov Documentation

About

Pavlov Home

What is Pavlov?

Pavlov Screenshot

We've all made decks of flashcards and slogged through them to study (oftentimes boring) material. Wouldn't it be great if the flashcards magically shuffled themselves to optimize your study time? Wouldn't it be great if they sung to you and danced and entertained you while you studied?

This is Pavlov - efficient, entertaining study.

Pavlov uses easy-to-write "pluglets" for feedback mechanisms (entertainment) and question choice strategies (efficiency). Just pop a new pluglet in the right directory to expand your Pavlov universe.

PAVLOV 1.1.2 Now Available

(30 Jun 04) Download the latest version of Pavlov and enjoy -- it's FREE SOFTWARE. New features include:

If you murder a test using Pavlov, please drop us a note! If you like the program, please rate it at freshmeat.net.

165,000 Language Questions Now Available

The Pavlov Project, with help from The JDict project and the European software company Majstro Aplikajoj are pleased to provide a set of huge language learning question books. These books are "bidirectional," so that, for example, the "English/French" book could be used by an English speaker to learn French or a French speaker to learn English. The files can be downloaded at the Pavlov Project Page.

A much larger set of books should be available in September 2004. All books are in XML/Unicode format and distributed under the GNU General Public License.

Where's The Project Manager?

The Pavlov Project Manager, T.J. Willis, will be in Alaska, probably completely cut off from the Internet during July and August 2004. Direct emails will almost certainly not be answered during this time. Questions may be sent to the Pavlov Developer's Mailing List pavlov-devel@lists.sourceforge.net.

Pavlov News

PAVLOV 1.1.2 Now Available

(30 Jun 04) Download the latest version of Pavlov and enjoy -- it's FREE SOFTWARE. New features include:

If you murder a test using Pavlov, please drop us a note! If you like the program, please rate it at freshmeat.net.

165,000 Language Questions Now Available

The Pavlov Project, with help from The JDict project and the European software company Majstro Aplikajoj, is pleased to provide a set of huge language learning question books. These books are "bidirectional," so that, for example, the "English/French" book could be used by an English speaker to learn French or a French speaker to learn English. The files can be downloaded at the Pavlov Project Page.

A much larger set of books should be available in September 2004. All books are in XML/Unicode format and are distributed under the GNU General Public License.

Where's The Project Manager?

The Pavlov Project Manager, T.J. Willis, will be in Alaska, probably completely cut off from the Internet during July and August 2004. Direct emails will almost certainly not be answered during this time. Questions may be sent to the Pavlov Developer's Mailing List pavlov-devel@lists.sourceforge.net.

Pavlov User Exchange Online

(27 May 04) We've hacked together a facility to allow users to exchange books, themes, skins, quiz export templates, and velocity feedback pluglets using sourceforge's "Patch" facility. Look for the "Pavlov Exchange" links on the navigation bar to the left for direct links.

Coding Conventions and Developer Info Online

(17 Mar 04) A document for developers discussing tools, coding conventions, and best practices is now available on the Pavlov site.

Pavlov 1.0 Tutorial is Online

(18 Feb 04) Want to check out how it works before you download it? Have you used it and want to explore the advanced features? Check out our virtual tour.

BEE Editor Beta Release

BEE Logo (16 Feb 04) BEE is a tool to easily and efficiently create questions for Pavlov and store them in the framework of books and chapters provided by the Pavlov Book XML Document Type Definition. The best thing is that you don't have to know anything about XML to use BEE!

Of course, as an open standard, you can use any sort of XML editor you want (even WordPad in Windows, if you really want) to edit Pavlov Book files. But BEE is specially designed to let you spend less time editing and more time learning (or making your victims learn).

BEE Editor Tutorial

(8 Feb 04) Take a virtual tour of the BEE Editor Preview Release online. Available HTML format.

PAVLOV 1.1B1 API Documentation Online

(17 May 04) Pavlov is not just a program, it's software. If you're a Java developer and you want to do some of the things Pavlov does in your own program, you can use the Application Programmer's Interface in your own programs under the terms of the GNU General Public License. Note that the API docs are linked to the 1.1B1 source code: click a method name to see the source code.

How To Write Velocity Pluglets

(18 May 04) The soup-to-nuts guide on how to write a Velocity Pluglet for Pavlov. If you can write a HTML page, you can write a Pluglet, and customize the bejesus out of your learning experience.

Installing Pavlov

Installing Pavlov

Note
Updated 22 May 04 For 1.1X Releases

First off, you have to have Java (version 1.5.0B1 or later) installed on your computer. You can download it at http://www.java.com.

Note
Pavlov 1.0 only required Java 1.4.

Now download Pavlov. Pavlov releases are distributed in familiar-acting installers. The full installation is about 6 MB, so you should have 12 MB of available disk space to install it. Pavlov takes about 8MB of RAM to run, but big pluglets can increase that to around 30MB of RAM.

Download the appropriate installer. The ".jar" installer runs on any java-capable computer. On PC's and Macs you should be able just to double-click the ".jar" installer and be off and running.

Note
Experience has shown that the ".jar" installer works slightly better than the ".exe" installer. (For you experts: the .exe asks the user to type in the location of java.exe if it can't find it, which might be a bit intimidating.)

Since the 1.0 release, the installer will create two files "Pavlov.bat" and "Pavlov_guest.bat" (.sh in Unix). You can double-click on these to run Pavlov. There is also a Bee.bat file for creating books of your own questions.

Note
Double-clicking the "pavlov-1.XX.jar" file probably won't work, as it won't load all the jars in Pavlov's "lib" subdirectory.

If it doesn't work, your computer probably doesn't know where to find the java program (java.exe on windows). You can edit the run.bat or run.sh files to tell your computer where to find java.

Note
If Pavlov starts to run, then freaks out, you're probably using an older version of Java. (If you run Pavlov from a console, it's not unusual to see a bit of "spam," especially in the Beta releases.)

If you're having problems with the installer or understanding the documentation, try our Forum to see if someone else has already answered the question, or tell us what's going on and we can try to help. Nobody here is going to give you a hard time for asking a question.

Pavlov Project Help Wanted Page

Contributing (your time) to Pavlov

There are many many ways that you, yes you can get involved in the Pavlov project. Here are a few:

Be an Active User

If you could get your browser to this web page, you should be plenty savvy enough to use Pavlov productively and think of things that need to be done, and ways it can be used in your world.

The sky's the limit!

Write a Pluglet

Pavlov's strengths lie in the pluggable nature of its feedback and question selection strategies. Pavlov would be a lot more user-friendly, and useful, with 100 pluglets available instead of 15. Someone new to programming in Java or programming period could very well write pluglets. I'd recommend this: go to java.sun.com and download Java (the name will be something like "J2SE1.5.0B..."). Look through their documentation on how to write an Applet. (Applets and Pluglets are not the same thing, but they're kissing cousins.) Then come back here and look at the Pluglet documentation. A lot of things will look familiar. Then do what every new programmer does when in a new environment: read the documentation and experiment. It's a lot of fun.

Note
With Pavlov version 1.1 you don't have to know Java to write a pluglet. Look for the documentation on how to write a Velocity Pluglet -- use HTML and a little programming to make a feedback pluglet!

Do Science

I'd love to have a professional educator or psychologist do a case study on Pavlov.

Hack The Core

There is need for experienced programmers to improve and expand the core Pavlov code. It's mostly in good shape, but there are API modifications and implementation cleanups lurking around that another pair of eyes would see before I would. Expansion brings up some really interesting problems, like how to use AbstractUIFactory to run Pavlov on a Palm-Pilot, how to back data to a RDBMS, how to implement in various client-server settings, etc. There are cobwebs in some packages that really need to be swept away.

Steal This Code

Well, use it in accordance with the GNU General Public License, but it's almost the same thing. The best way to see if an API is flexible enough is to try to use it in a completely different setting. I've had to make about 6 changes in writing BEE, which is almost exactly the same application as Pavlov.

A Brief History of Pavlov

Pavlov's History

Pavlov has been in private development for 4 years. Bored with writing and flipping flash cards for the United States Coast Guard's Captain's license, I wrote a Perl Script to do it and hacked in statistical choice of questions and question history logging.

After a hard disk crash in 2000, I (grudgingly) reimplemented it in Java.

Noticing how successful HotOrNot.com was at keeping users (i.e. me and my neighbor Josh) clicking their buttons, the idea occured to me to have my program show pictures of bikini-babes when the user got correct answers. This proved extremely successful with my Navy shipmates who borrowed Pavlov to study for advancement examinations and Enlisted Surface Warfare boards.

As the program grew in complexity, I went through several stages of refactoring and API refinement. Writing plugin support for "question selection strategies" and "feedback pluglets" allowed me to simultaneously decrease the core source code complexity and increase its feature set. Now, it's not "bikini-babe-centric," anyone who can write a normal applet can use his imagination and write a feedback pluglet to provide positive and negative support based on a wide variety of historical data that's stored about the user.

Note
With Pavlov 1.1X, you don't need to be able to write a Java program to create a pluglet. Now you can do it using HTML and some minor programmatic content using the Velocity Template Language.

Question selection strategies, similarly, are only a matter of a programmer using his imagination, writing a simple program, and dropping the class or JAR file into the pluglets/strategy/ directory.

The core source is hovering around 130 Java classes and 14,000 lines of code. Heavily used technologies include XML, Swing, and runtime class loading. It has been the target of several bouts of intense refactoring. Abstraction and design patterns are the rule rather than the exception throughout the code.

Note
With 1.1B1 it's more like 100 classes and 16,000 lines of code.

Pavlov's evolution has resulted in several packages suitable for general use that are available under the GNU General Public License (GPL).

My main goals in sourceforging this project are:

  1. make the Pavlov program and API's available to users and programmer-users,
  2. get suggestions/assistance on problems remaining in the code and/or architecture,
  3. provide a home for pluglet developers to create and distribute feedback & question strategy pluglets,
  4. to provide a home for the collection and distribution of content: Library files of questions, and,
  5. to encourage different implementations for abstract classes, i.e. DBMS storage of questions and statistics, a servlet Abstract UIFactory implementation, PDA-friendly implementations, etc.

If you've read this far, you are either a very bored person or a potential contributor. If you'd like to take part of Pavlov and run with it, whether it be part of the core, pluglets, writing a "book" of questions, documentation, a study on Pavlov's efficacy in the classroom, or whatever, there's plenty of room in the project for you. Any contributor who would like to get his or her name mentioned has but to ask.

Download

Other Pavlov Sites

How To

Pavlov Code Conventions

Pavlov for Developers

As more people start working with the Pavlov code, it's important to recognize and maintain the strengths in the code and to attack its weaknesses. If something in this document doesn't make sense to you, that's OK -- do a quick web search to try to get an explanation. If that doesn't work, feel free to post a message on the Pavlov forums.

Tools

The following tools are necessary or useful to have installed on your computer:

Note
If you don't intend to recompile Pavlov (i.e. if you aren't a programmer), you can get JRE1.5.0B1 or later -- the Java Runtime Environment. This is much smaller than JDK1.5.0B1.

Readable Code

Let's start with the following code conventions:

  1. Avoid special characters (smart-quotes, copyright signs, etc) at all costs
  2. Indent your code so that it's readable
  3. Avoid going over 80 characters per line
  4. Label problem areas in code with "//FIXME: Description of problem"
  5. Name temporary variables better than TJ does

The following depend on your IDE. When Ant's checkstyle task can handle tiger (jdk1.5) code, it will become much easier to enforce.

Good Code

Try to adhere to these rules as much as possible. If you see an instance where a rule is violated, at least add a FIXME or else fix the problem. Many of these come from Joshua Bloch's book "Effective Java Programming Language Guide."

  1. [Bloch01 #47] Don't ignore exceptions
  2. [Bloch01 #12] Minimize the accessibility of classes and members
  3. [Bloch01 #23] Check parameters for validity.
  4. [Bloch01 #38] Adhere to generally accepted naming conventions
  5. [Bloch01 #29] Minimize scope of local variables
  6. [Bloch01 #28] Write doc comments for all exposed API elements
  7. [Bloch01 #34] Refer to objects by their interfaces
  8. [Bloch01 #33] Beware the performance of string catenation
  9. [Bloch01 #15] Design and document for inheritence or else prohibit it
  10. Use final variables and parameters where possible.
  11. Use tiger-style looping as possible
  12. Use tiger-style typechecking as possible
  13. Strive to decrease javac -Xlint warnings
  14. Write unit tests as possible
  15. Use assertions to check preconditions and postconditions
  16. Use log4j instead of System.out.println
  17. If a method doesn't depend on the object's state, make it static

Good Documentation

Even with a great deal of recent effort, Pavlov's documentation is not in great shape. Check out How To Write Doc Comments for Javadoc to learn how to do it right. Apart from JavaDocs, it's good to have good, normal comments in your code, like: 

070  /**  
071   * Returns the next question answered fewest times or null if problem.
072   *
073   * @return a <code>QuestionData</code> value
074   */ 
075  public QuestionData getQuestion(Vector<QuestionData> exclusion) {
076   
077    QuestionData q = null;
078  
079    int lowest = 10000000; // FIXME: should be Integer.MAX_VALUE
080
081    for(QuestionData x: questions) {
082        if(exclusion!=null)
083            if(exclusion.contains( x)) // if this question is in the exclusion vector 
084                continue; // go to next question
085        if (x.getTotal() < lowest) {  // this one's been asked fewest times
086            lowest = x.getTotal();
087            if(lowest==0) return x;
088            q = x;
089        }
090    }
091    return q; // question with fewest answers or null
092  }

Hey! Let's look at that example!

Since it's sitting there, let's make some comments on it.

This is what "code cleaning" is about, and while it's not as glamourous as some other aspects of development, it cuts down on bugs, makes the code faster, and shows everybody that you're smarter than the original developer. :)

Design

Object Oriented Design (OOD) isn't a newbie topic, but an understanding of some design patterns will make parts of the Pavlov code easier to understand. You can read about these on the Web, in the famous "Gang Of Four" book "Design Patterns", or [Stelting02]. The following patterns are often used.

Baby Steps

To many programmers, this document, not to mention the size of the Pavlov code base may seem overwhelming. When you make a task for yourself, try to make it small enough to handle in one session. For example the task "I'm going to decrease the scope of all the variables in pavlov" is too big. I often pick a subpackage, like pavlov.user or pavlov.library and bang on it, compile, get rid of Xlint warnings, run the program for a while, then check my code in. The longer your code is different than the CVS repository, the more of a chance of a check-in collision (count yourself lucky if you don't know what that means) or breaking the build. These problems are bound to happen, but we should try to minimize them as much as possible.

Keep it Friendly

I started working on Open Source projects in about 1990. Some projects were great because the developer community was talented and supportive of each other -- everybody learned a lot, had fun, and made cool software. In others, conflicts arose and things got nasty. (I remember one morning when a developer at Lawrence Livermore National Laboratory got a 80-gigabyte email for breaking a build.) As this community grows, I require that it remain courteous. On the other hand, sometimes people won't be able to help in what you feel is a timely manner, and you may feel offended. One of the things that project work like this teaches aspiring programmers is to be thick skinned and self reliant.

Recommended Environment

If you're a seasoned developer, you probably have strong views about what development environment you use. I don't have any interest in getting into an argument like "xjpicovim rules and winusurper sucks!" But, if you are starting out from scratch, I can make a couple of suggestions.

Install linux! (I'm almost kidding.)

Linux is a great environment, it's free-no-cost and free-liberty. Blah, blah, blah. It takes some work and some disk space to get it installed and it takes a while to get used to it. But in the long term, its worth it.

But, you want to get started hacking out code quick. Cygwin-X provides a set of tools that make your computer "feel like" Linux with XWindows and it's pretty painless to install. You can get all the tools you need to work with sourceforge (ftp, ssh, scp, cvs) and great time-tested editors like XEmacs and vim. Getting to know these tools, especially if you're a college student (in math, physics, computer science, engineering), is really, really useful.

There are some open-source Java IDE's that are probably worth looking at, but I don't have an informed opinion on them. At the least, they should provide text highlighting, auto indenting, and CVS support.

Note
Since I wrote this, I've downloaded and installed jEdit. When its plugins begin to support JDK1.5 better, I'll be able to wholeheartedly recommend it. It rocks for JDK1.4 code. It's also very good for XML code (such as editing Pavlov books.)

Bibliography

These are books I've drawn (heavily) on in preparing this document.

[Bloch01] Bloch, Joshua. Effective Java Programming Guide. Addison-Wesley, Boston, MA, 2001.

[Stelting02] Stelting, Stephen and Maassen, Olav. Applied Java Patterns. Sun Microsystems Press, Palo Alto, CA, 2002.

[Fowler04] Fowler, M., Beck, K., Brant, J., Opdyke, W., Roberts, D. Refactoring: Improving the Design of Existing Code. O'Reilly and Associates. 2004.

[Simmons04] Simmons, Robert. Hard Core Java. O'Reilly and Associates. 2004.

Pavlov For Developers FAQ

External Tools

These are some of the tools that are used in and around the Pavlov project. You don't necessarily need any of them to be an active developer, although Ant and a CVS client are pretty close to necessary.

Note
The mention of any software in this document is not meant to imply that that software's creators endorse Pavlov. This document is instructional, not promotional in nature. This note addresses an item in some versions of the BSD and Apache licenses.
Apache Ant

Apache Ant Project

Ant simplifies compiling Java files to class files, and a host of other, similar tasks. It's basically a Java-centric replacement of the UNIX "Make" command. Ant uses an XML file, usually called "build.xml" to get rules for compiling a whole tree of files at once.

Apache Forrest

Apache Forrest Project

Apache Forrest is used to maintain the Pavlov web site. All the pretty HTML and links and stuff is generated automatically by Forrest. The web site documents, like this one, are generated from XML documents which focus on content rather than form.

Apache Log4j

Apache Log4j Site

Log4J is an open-source system for logging, i.e. reporting errors, warnings, informational messages, etc. It replaces "System.out.println" for debugging code, while adding a great deal of extra functionality.

CVS

CVS For New Users

Jim Blandy's Intro To CVS

sourceforge.net's CVS info (See section F)

CVS stands for "Concurrent Versioning System." It allows several people to edit a file or set of files at the same time and minimizes "collisions."

In the old days, people used to use RCS (Revision Control System), where they would check out a file, work on it, and then check it in. Nobody else could edit the file while it was checked out. People would go on holiday with a file checked out and return to find their house burnt down by a mob of angry co-contributors.

CVS takes a little getting used to, and is by no means the easiest program in the world to get installed. It is, however, one of the most useful programs in the world to use for collaborative development.

emacs, jedit, vim, joe, pico, xedit, yadda yadda yadda

GNU Emacs Site

jEdit Site

These are text editors you'll hear referred to every once in a while. While it's possible to edit a Java program file, XML document, HTML document, etc in a commercial word processor, text editors such as these are geared towards doing it more efficiently and cleanly. Developers get extremely attached to their text editors. Few people know this, but the siege at Troy was started when Paris told Menelaus that vim was better than emacs. Zeus, the thunder maker and supreme god, knew that emacs was best and gave victory to the Greeks.

ICQ (I seek you)

ICQ Site

ICQ (say it out loud) is a free communication tool, that includes functionality like instant messaging. ICQ has been vital and free for at least 8 years. ICQ is recommended for project members.

JUnit

JUnit.org

JUnit is a framework for writing unit tests. Avoiding formality, a unit test simply tests a chunk of code, usually a method, to determine if it functions correctly in a variety of situations. JUnit has been found to be extremely useful when multiple developers are working on a program, and is considered by many to be a cornerstone of eXtreme Programming. Pavlov's unit tests, such as they are, are located in the test subdirectory.

UMLGraph

UMLGraph Site

UMLGraph generates UML diagrams from doclet tags. If you see a doclet tag in Pavlov code that you're not familiar with, it's likely a UMLGraph tag. It's a back-burner project to get good UML diagrams from UMLGraph.

VAInstall

VAInstall Site

VAInstall is a GPL-ed program that creates installers, including all of Pavlov's installers. The configuration files that specify how the Pavlov installers are created are located in the pavlov/vai directory in the CVS repository.

PMD, JavaStyle, CheckStyle, Jalopy, and So Forth

PMD Site

JavaStyle Page

CheckStyle Site

I'm grouping these together as "code improvement" tools. They analyze your code and either reformat it or make recommendations for improving it. I'm not aware of any similar tool that works with JDK1.5 constructs, and many have problems with 1.4 code (which is to say asserts). The picosecond that any of these tools starts to work with 1.5 code, I will start using it again.

Bundled API's

It's a hallmark not only of laziness, but of good design to not reinvent the wheel. Since Pavlov is distributed under the GNU General Public License, it can leverage software distributed under several open source licenses. Here is a quick intro to them.

Note
The mention of any software in this document is not meant to imply that that software's creators endorse Pavlov. This document is instructional, not promotional in nature. This note addresses an item in some versions of the BSD and Apache licenses.
jCharts

jCharts Project

jCharts is an Apache-Licensed API for plotting line-graphs, scatter-plots, pie charts, and so forth. It's used by several Pavlov pluglets. It's lightweight, quick, and the output is very pretty. jCharts replaced Pavlov's "EasyGraph" module around January 2004. jCharts is a trademark of Nathaniel G. Auvil.

JavaHelp/jh.jar

JavaHelp Site at Sun

JavaHelp is software written by Sun Microsystems to provide a familiar help system in Java programs. Click "Help Topics" in Pavlov or Bee to see it in action.

sillyview

sillyview site

sillyview is an API that spun off from Pavlov. It uses Velocity (cf below) to provide a model-view-controller framework based on template files.

steelme

steelme site

steelme is another API spun off from Pavlov. In short, it provides the Themes submenu of the Prefrences menu. In shorter, it lets Pavlov use pretty colors and fonts (or ugly colors and fonts).

Apache Jakarta's Velocity

Velocity Site

Velocity is a very, very pretty piece of software created by the folks at the Apache Jakarta project. It's hard to put velocity in a nutshell, but here's my try: you start with a text "template file." It could be XML, HTML, RTF, PDF, or any sort of text file -- it doesn't matter.

Now, say there are some "tokens" or string values in the template file you want to replace with a set of values determined in. Velocity lets you do this in a very cool way. You can pass any sort of Java object "into" the template, evaluate methods, do loops and evaluate conditionals.

Pavlov uses HTML templates in many places. The main quiz screen is specified by a HTML template. So is the library view on the left side of the main screen. So is the login widget, the "Export Quiz" widget, and so forth. Velocity Pluglets are simply HTML templates that are given information about the user's current state every time he answers a question.

Templates are converted to Swing entities by the sillyview package. sillyview can also render these templates to other environments, such as servlets.

Apache Xerces2 Java (xercesImpl.jar/xml-apis.jar)

Xerces2 Java Site

Pavlov uses XML heavily. Xerces is a free API for parsing (and doing other stuff to) XML files. Hence, Pavlov uses Xerces heavily. QED.

What the Heck?!?

You just started looking through the code, and it looks more like C++ than Java? See a "cat" or an "rb" and wonder what it is?

What's a "cat" and why is it everywhere?

cat is the standard name for a log4j Category or Logger, an object that can create error, warning, info, debug messages and so forth.

What are asserts all about?

JDK 1.4 and later provides assertions. These are checks, usually of preconditions and postconditions in methods, that can be enabled or disabled at runtime. People spend a lot of time arguing about best-practices with assertions. It's generally agreed on that they shouldn't be used to check that method parameters are valid, but you may find places in Pavlov where they're used this way. If you do stumble upon an assert used to check parameters, tag it with a FIXME.

What's an "rb" and why is it everywhere?

ResourceBroker is a wrapper with some convenience methods for the java.util.ResourceBundle class. It allows Strings to be stored in properties files instead of being hardcoded into the Java program. This makes it easy to a) tweak strings, and b) internationalize the program.

What's this HashMap<String, Object> stuff?

As of JDK1.5, Java allows strong typing in its Collections framework. This is great if you have concerns that somebody might put a CurryChicken object in your vector of IceCream objects. I think we all know what havoc can ensue when you're expecting IceCream and get CurryChicken instead.

What's this for( String x : vec) stuff?

Another JDK1.5 feature. Say you have a Vector<String> vec, and you want to loop through it. You could make an Iterator, an Enumeration, loop through it with elementAt(), and so forth. (Furthermore, in 1.4 you'd have to cast your loop variable to String). This construct does all that for you, decreasing the amount of code and the possibility of little mistakes.

What are FIXME's for?

A FIXME comment is used to point out that something is implemented poorly, bug-prone, inefficent, or so forth. Developers can search for the string FIXME when looking for something to fix. If you see suspicious code, feel free to plop a FIXME with a brief description of the problem.

You'll also see FIXED comments, which should replace the FIXME when the problem is corrected. FIXED comments should last "for a while" but should be removed sooner or later. Later is probably better than sooner.

Miscellany

The Coding Standards seem confusing/draconian/etc...

The Coding Standards document is a mix of simple and advanced topics, which is probably not a good idea. You don't have to understand the Model-View-Controller pattern to tweak some code. CS should not make you want to jump out of a window or be nervous about contributing. It should provide guidance, especially when you're getting close to committing some changes.

If you are nervous about breaking the coding standards, you may take comfort in the fact that the chunk of code that was lambasted at length to illustrate the standards was written by the project manager. Nobody's perfect.

If there's something in the CS that's patently confusing, ask about it on the pavlov-devel mailing list.

I Can't Get CVS to Check Out Pavlov

There are a buzillion CVS clients out there, and I use precisely one (cvs/openssh for cygwin/linux). I think, especially if you use jEdit, the GruntsPud CVS Client is the second easiest one in the world to set up. The key is to get the CVSROOT and CVS_RSH variables set up right.

If, while you're setting up, you see an option named "pserver," it shouldn't be there. In short, pserver is bad, ext is good. Everybody join hands and repeat: "pserver is bad, ext is good." You have to have some sort of secure socket or secure shell support to use CVS at sourceforge if you plan on checking something in. Many clients include some ssh support, you just have to figure out how to make it work.

That said, here's what a CVS session looks like in CygWin and Linux: 


$CVSROOT = :ext:YOURSFNAME@cvs.sourceforge.net:/cvsroot/pavlov 
export CVSROOT 
$CVS_RSH = /usr/bin/ssh 
export CVS_RSH 

then, you'd check out the repository once: 

mkdir ~/foo 
cd ~/foo 
cvs co .  ( "period" for everything -- cvs co net for just core source) 

then edit a file (say, put a space in a comment or something) 
cd ~/foo 
vi net/sourceforge/pavlov/event/AnswerEvent.java 

then checkin 
cd ~/foo 
cvs ci 

then (say the next day) apply diffs from the server to your copy of the code 
cd ~/foo 
cvs update 

or, you could just update the event directory: 
cd ~/foo/net/sourceforge/pavlov/event 
cvs update
What's tiger?

Tiger is slang for JDK1.5X/JRE1.5X.

Where do I find stuff to do?

Here's some pointers:

I'm philosophically against "assigning projects," it stifles innovation and lowers morale. But, sooner or later you will get a message like "hey, can you take a look at X?" that's just a sign that the other developer thinks you have good eyes. If you're still having trouble finding something to work on, send an email to the list and ask if anybody needs help with something.

Can a GPL Project use Apache-Licensed Modules?

According to Apache, yes. There are rumblings that GNU doesn't agree, but I've yet to see anything concrete. There's never been any beef with using BSD modules in a GPL project, so I can't really see what the issue would be. I'm a rabid GPL zealot, but I really can't see what the issue would be.

Shouldn't it be called Skinner?

Maybe skinlov or something. Pavlov makes sense from a meta-viewpoint: conditioning a positive response to studying is Pavlovian. The operant conditioning gets the user to learn questions, the Pavlovian aspect conditions the user to respond in a positive manner to the stimulus of "study time."

Is it "BEE" or "Bee"

Yes, it is "BEE" or "Bee." BEE is, more or less, an acronym for "Book Editing Environment," so, it should be capitalized, but is often not in practice.

Philosophy

What's the goal of the Pavlov Project?

To provide a comfortable, customizable environment for efficient study.

The development of the emacs text editor has deeply affected my goals with Pavlov. My dog could write a text editor -- if there aren't 10,000 text editors out there, I'll eat my hat. What makes emacs special is that it is, and has been, so customizable. As an end user, without touching the core source code, without writing a line of C code, you can dramatically affect how emacs looks and how it works. The result is that the user community adapts emacs to solve the problems they have with it. They share their adaptations, and emacs en-grande develops organically.

This isn't meant to detract in any way from the amazing way that the emacs core has grown with it's staggering network of coders. I'm just saying that the magic bit is the customizability.

Here are some ways that we've strived to make Pavlov customizable:

A lot of effort is going into releasing a Java servlet version of Pavlov. This will decouple using the program from installing it, and should increase the user base by orders of magnitude.

Why write another "flashcard" program?

There wasn't one that did what I wanted. I'd say 25% of the ones out there have their questions hardcoded. Another 25% can't handle media, like pictures and sounds, embedded in their questions. I'm not aware of another one that supports pluggable feedback mechanisms, pluggable question selection strategies, skins, and so forth.

Get to Know Everybody

I know I'm repeating myself here, but it bears repeating. A lot of the joy of collaborative development comes from talking to other developers, discussing ideas, sharing victories and defeats, and socializing between builds. Coaching a new developer can be particularly rewarding. 'nuff said.

Being Nice

As computer scientists, engineers, mathematicians, and so forth, we tend to be a bit abrupt when someone asks a question. This isn't conducive to creating a vital community. There is no place in the Pavlov community for flaming users or other developers. Don't do it.

Directory Structure

Pavlov has many, many directories. A current developer directory tree, discounting build directories, CVS directories, and Javadocs has 106 directories. This document is almost guaranteed to not keep up with changes in the directory structure, but should provide a good basic idea of what is where.

Writing A Velocity Pluglet

About This Document

One of the big improvements in Pavlov 1.1 is the leveraging of the Apache Jakarta Project's Velocity Template Engine to create templated Pluglets and Skins. This document describes how to write a Velocity Feedback Pluglet for Pavlov.

Step 1: Find The VelocityPluglet Directory

Let's assume you already have Pavlov 1.1B1 or later installed. Find the directory it was installed in. Now, there will be a subdirectory called pluglets and its subdirectory of pluglets/velocity. In the 1.1BX release, there are two subdirectories here called aliengrades and navylife. Every subdirectory of pluglets/velocity is scanned at startup for a file named index.vm. Those with a valid index.vm are accepted and added to the Feedback Menu in Pavlov. So, for example, on my machine, I have 

/home/haus/pup/pluglets/velocity/aliengrades/index.vm
/home/haus/pup/pluglets/velocity/navylife/index.vm

let's take a look at one of these.

Step 2: Look at an Example

We open up the file pluglets/velocity/aliengrades/index.vm and see something like this: 

01   <HTML>
02   <HEAD></HEAD>
03   <BODY BGCOLOR="black">
04 
05   <TABLE HEIGHT="223" WIDTH="304">
06   <TR>
07   <TD HEIGHT="223" WIDTH="304">
08   #set ( $right = $ANSWER_EVENT.getNumberOfCorrectAnswers() )
09   #set ( $tot= $ANSWER_EVENT.getNumberOfAnswers() )
10   #set ( $perc  = 100 * $right/$tot )
11
12   #if ( !$perc )
13     #set ($img ="logo.jpg")
14   #elseif ( $perc < 59 )
15     #set ($img ="f.jpg")
...stuff deleted...
16   #else 
17      #set ($img ="aplus.jpg")
18   #end
19   <IMG SRC ="$BASE_URL$img">
20   </TD>
21   </TR>
22   </TABLE>
23
24   </BODY>
25   </HTML>

Let's make a few observations:

Note
Java doesn't like some META tags, and it hates bad HTML. If you have problems debugging a VelocityPluglet, try to remove META tags and simplify the HTML.

Step 3: Use Advanced Velocity Features

The best source for information on advanced Velocity features is at Apache Jakarta Project's Velocity Site. There are some neat tricks on display there.

Step 4: Get More Information From Pavlov

Pavlov passes a great deal of information to your template using the AnswerEvent class. You can get information from the AnswerEvent by using it's methods. A few examples:

$ANSWER_EVENT.getQuestionData().getPercentage() Percentage of correct answers over whole user history
$ANSWER_EVENT.getUser().getName() User's login name.
$ANSWER_EVENT.getBookData().getTitle() Title of book in use
$ANSWER_EVENT.getChapterData().getStrategy().getName() Name of the question selection strategy in use
$ANSWER_EVENT.getChapterData().getQuizCollectionData().numQuizzes Number of quizzes this user has taken on this chapter
$ANSWER_EVENT.getChapterData().getQuizCollectionData().totalAsked Number of questions this user has answered over all quizzes on this chapter

The point here is not to list all the possible types of information you can glean from the system, but to illustrate that there is a lot to choose from.

Step 5: Publish

When you get a feedback pluglet that you like, send it to the Pavlov project. We'll need copyright information and have to filter out obscenities, but other than that, we'll be happy to make your pluglet available. That way, others can not only use your pluglet, but learn from it as well!

Writing A Custom Skin for Pavlov

Writing a Skin for Pavlov

One of the big improvements in Pavlov 1.1 is the leveraging of the Apache Jakarta Project's Velocity Template Engine to create templated Pluglets and Skins. This document describes how to write a custom Skin for Pavlov.

Step 1: Find The Skins Directory

Let's assume you already have Pavlov 1.1B1 or later installed. Find the directory it was installed in. Now, there will be a subdirectory called resources and its subdirectory of resources/skins. In the 1.1B1 release, there are several subdirectories of skins, like "cipher" and "euphoria." Every subdirectory of skins is scanned at startup for subdirectories that have velocity template files named Library.vm, Logon.vm, QuizPanel.vm, and Welcome.vm. Pavlov also looks for a file called Theme.theme which specifies the fonts and colors to use for the skin.

Note
Don't spend any time working on the Logon and Welcome templates. They need to be there, but aren't really used. They won't need to be there in a near-future release.

Let's take a look at one of these examples.

Step 2: Look at an Example

We open up the file QuizPanel.vm in the cipher directory and see something like this: 

01 <html>
02 <head>
03  <title>pavlov quiz: $BOOK_NAME: $CHAPTER_NAME</title>
04 </head>
05 <body text="#ffffff" bgcolor="#000000" link="#ffffff" vlink="#ffffff" 
   alink="#ffffff" background="${BASE_URL}cipher.JPG">
06 pavlov quiz: $BOOK_NAME: $CHAPTER_NAME
07 
08 <HR>
09  <table width="100%" height="400" border="1">
10    <tbody>
11      <tr width="100%" height="200">
12        
13 #if( $QUESTION_IMAGE!="")
14       <td valign="Top" height="200" colspan="1">
15        <div class="P"><big>$QUESTION_TEXT</big></div>
16        </td>
17        <td><img src="$QUESTION_IMAGE" align="Left">
18        </td>
19        
20 #else       
21        <td colspan="2" height="200" >
22        <div class="P"><big>$QUESTION_TEXT</big><</div>
23        </td>
24      
25 #end      
26        </tr>
27      <tr>
28        <td colspan="2">
29        <table width="100%" border="0" height="200">
30          <tbody>
31            <tr>
32              <td height="100%"><!-- start a -->
33              <div class="P"><big><a href="${BASE_URL}$A_BUTTON"><b>
34       A.</b></a>
35  $A_ANSWER </big></div>
36              <hr>
... stuff deleted...
37             </td>
38            </tr>
39          </tbody>
40        </table>
41      </tbody>
42   </table>
43</body>
44</html>

Let's make a few observations:

Note
Java doesn't like some META tags (charset specifiers seem to be the primary offenders), and it hates bad HTML. If you have problems debugging a VelocityPluglet, try to remove META tags and simplify the HTML.

Step 3: Set up A Default Theme

When you've got your HTML how you want it, you've probably made some decisions on what sort of fonts and colors you want the skin to use. You can ensure that the rest of the Pavlov application uses these fonts and colors by providing a file Theme.theme in your skin directory. You can create this file by hand or using the "Theme Editor" available in Pavlov. (If you use the theme editor, you'll have to save your theme, then copy if from resources/themes/YourTheme.theme to resources/skins/yourskin/Theme.theme.)

Note
You can skip the next paragraph if you're planning to use the ThemeEditor to create your themes.

As an introduction to themes, let's take a look at the Binary.theme file. The colors are comprised of triplets of numbers from 0-255 describing the amount of red, green, and blue in the color. Attributes like fontSize, name, and fontName are pretty self-explanatory. The best way to understand what parts of the GUI correspond to the various colors is to use the Theme Editor in Pavlov. 

#Tue May 11 20:41:04 EDT 2004
name=Binary
fontName=Microsoft Sans Serif
text2=153,153,153
text1=255,255,255
black=255,255,255
fontStyle=1
white=0,0,0
primary3=0,0,0
secondary3=31,31,31
primary2=0,0,0
secondary2=204,204,204
primary1=204,204,204
secondary1=0,0,0
fontSize=14

Step 4: The Other Template Files

The files Logon.vm and Welcome.vm shouldn't be part of the skin system, but they have to be there for now. You shouldn't spend any effort customizing these templates. The Library.vm file controls how the books and chapters containing questions are displayed to the user. You should customize Library.vm to agree with your QuizPanel.vm template.

Step 5: Use Advanced Velocity Features

The best source for information on advanced Velocity features is at Apache Jakarta Project's Velocity Site. There are some neat tricks on display there.

Step 6: Get More Information From Pavlov

Pavlov passes a great deal of information to your template. The default skin in skins/default displays all the information Pavlov passes. If you want to display more or less information, feel free.

Step 7: Publish

When you get a skin that you like, send it to the Pavlov project. We'll need copyright information and have to filter out obscenities, but other than that, we'll be happy to make your skin available. That way, others can not only use your skin, but learn from it as well!

Known Bugs and Issues

Pavlov Exchange

CVS Repository

Whole Site

Pavlov Tour

Starting Pavlov

Slide 1: Starting Pavlov

This is what Pavlov looks like when you start it up. On the left, you see the "Quiz Selector" displaying books and chapters of questions available for you to study.

Starting Pavlov

Choosing A Quiz

Slide 2: Choosing a Quiz

Click on a chapter to start a quiz.

Note
Apparently, when starting the first quiz, you may have to double-click the link as of Pavlov 1.1B1.

pavlov screenshot

Starting a Quiz

Slide 3: Starting a Quiz

Starting a quiz pops up the Quiz screen. You are presented with a question and four possible answers. Notice that Pavlov keeps track of how you have done on this question in the past. I've answered this question correctly three of three times.

pavlov screenshot

Continuing A Quiz

Slide 4: Continuing a Quiz

You can minimize the quiz selector using the splitpane control (the arrows between the quiz selector and the quiz panel). Note that Pavlov handles question images nicely.

If you look closely at the bottom of the image, you'll see how this skin keeps track of score and elapsed time. Information about my progress in the chapter is displayed towards the top.

pavlov screenshot

Monitoring Your Progress

Slide 4A: Monitoring Your Progress

Pavlov offers several ways to monitor your progress as you work on a chapter. Most use information from every question you've ever answered in a quiz. Most are graphical. Most of the following tools are available from the "Feedback" menu.

Quiz-Centric Progress

The most basic statistic in a quiz is your score. Watching your score go up and down gives you a feel about how you're doing. The "Progress Graph" shows exactly this:

pavlov screenshot

You can monitor how you have progressed over every quiz you've taken in this chapter by watching the "History Graph:"

pavlov screenshot

The Red areas represent the number of incorrect answers in that quiz, and blue the correct answers.

Chapter-Centric Progress

The simplest monitor of how you've fared against a chapter in all your quizzes is the "Coverage Graph." This breaks the chapter into 3 pieces: questions you've answered right at least once(green), questions you've answered at least once with no correct answers(red), and questions you've never answered (black). Here's what one looks like:

pavlov screenshot

The "Frequency Graph" gives you a much more detailed look at how you're attacking the chapter. It lists all the questions across the bottom of the graph. Red areas represent incorrect answers and blue areas represent correct answers.

pavlov screenshot

Analyzing this graph can give you a lot of insight into how question selection strategies work, and more importantly, how much you know about the information in this chapter.

Textual Progress Monitoring

Arranged on the quiz panel are various indicators of how you are progressing on the quiz. Which pieces of information are displayed, and where, depends on the designer of the skin you are using. This skin was obviously designed by someone obsessed with numbers.

pavlov screenshot

Using Feedback Pluglets

Slide 5: Using Feedback Pluglets

Now it's time to have fun. Open the "Feedback" menu and look at the pluglets that you have installed. Selecting a pluglet activates it, deselecting it deactivates it.

pavlov screenshot

Using Feedback Pluglets

Slide 6: Using Feedback Pluglets

Let's activate the "Alien Grades" pluglet. This assigns you a grade based on the percentage of your correct answers.

pavlov screenshot

Using Feedback Pluglets

Slide 7: Using Feedback Pluglets

Maybe "Alien Grades" doesn't excite you. Or maybe you want to use Pavlov to teach a child arithmetic. Looking through the pluglets available, we see that there's one that shows pictures of cute animals (you can plug in images of whatever you want) . If you answer a question correctly, it makes the picture bigger. Incorrect answers make the pictures smaller. That might do the trick...

pavlov screenshot

Using Strategy Pluglets

Slide 8: Using Strategy Pluglets

Pavlov allows you several different ways to pick the questions you study. Choosing "Lowest Percentage" lets you focus on the questions you have the hardest time answering correctly. Choosing "Answered Fewest Times" makes sure you study all the content in the chapter evenly.

pavlov screenshot

Using Themes

Slide 9: Using Themes

One of the ways to make a program more comfortable to you is to customize how it looks. The Preferences menu allows you to do this.

pavlov screenshot

Using Skins

Slide 10: Using Skins

Maybe this sort of visual environment is more soothing to you...

Note
Artwork (euphoria1024.jpg) by Barbara Lopez http://www.xerraire.com.

pavlov screenshot

Using Skins

Slide 11: Using Skins

... or maybe you're feeling spacey ...

Note
Image property of NASA, used in accordance with their guidelines. See LICENSE_SKINS.txt for more information.

pavlov screenshot

Using Themes

Slide 12: Using Themes

Or you can create your own custom theme.

pavlov screenshot

Exporting a Quiz

Slide 13: Exporting a Quiz

This shows you "Generate Hardcopy Quiz" dialog. Let's generate a simple web-page tutor with 25 questions (using the current chapter and question selection strategy).

Note
This dialog should be renamed soon.

pavlov screenshot

Export Quiz

Slide 14: Export Quiz

Here's the output from the "Export Quiz" on the previous slide. The user clicks on the answers he selects and is informed by a JavaScript if he was right or not.

Note
This "app" might break if there are quotes or single-quotes in the answers.

As with almost everything in Pavlov, you can specify the output with a Velocty Template Language template. It would be interesting to generate DocBook documents that can be converted to TeX, Postscript, PDF, etc...

pavlov screenshot

BEE Editor Tour

Starting Bee

Slide 1: Starting Bee

You can start Bee by clicking on the script (batch file, or shell script on Unix) in the Pavlov directory.

bee screenshot

Bee Startup

Slide 2: Bee Startup

When you start Bee, you have the options to create a new book, edit an existing book, or quit.

bee screenshot

Create A Book

Slide 3: Create A Book

You can use the wizard interface to create a book.

bee screenshot

The Book Editor

Slide 4: The Book Editor

The Book Editor allows you to edit the author, title, and description of the book, as well as editing the book's chapters.

bee screenshot

The Chapter Editor

Slide 5: The Chapter Editor

This shows the Chapter Editor, which allows you to edit the Chapter's author, title, and description, as well as all its questions.

bee screenshot

The Chapter Editor

Slide 6: Chapter Editor

The edit menu allows you to copy, paste, and insert, and delete questions, as well as undoing your last edit and normalizing question ID's.

bee screenshot

Inserting Questions

Slide 7: Inserting

When inserting questions, Bee ensures that you have a unique question ID, minimizing the possibility of duplicate IDs.

bee screenshot

The Question Factory

Slide 8: The Question Factory

If you're creating a bunch of similar questions, consider using the question factory. This saves you a lot of time and repetitive typing. Incorrect answers are filled in automatically. Keep in mind that Bee just compares answers character by character to pick wrong answers. So, "Richard Nixon" could be chosen as a wrong answer, where "Richard M. Nixon" was the right answer.

bee screenshot

Question Factory Output

Slide 9: Question Factory Output

This slide shows the questions generated by the question factory session in the previous slide. Notice how much redundant typing was saved.

bee screenshot

Sorting Questions

Slide 10: Sorting Questions

You can sort all the questions by various criteria.

bee screenshot

More About The Book Editor

Slide 11: More About The Book Editor

Back to the Book Editor, notice that you can copy, insert, and delete whole chapters at once. You can also create new chapters from here.

bee screenshot

Bee is A Beta Release!

Slide 12: Bee is A Beta Release!

Note
BEE is now a Beta Release with no problems reported. However the cautions in this document still are prudent to observe.

This is a very early release of Bee. It might behave strangely. If you use it, please work on copies of the book files not the original book files

Here's the The Free Dictionary's definition:

alpha software

Noun 1. alpha software - a first release of a software product that is usually tested only by the developers

If you find problems or would like certain features, please feel free to post in the forums at the Pavlov project page.