Updated readme with requirements, docs

OTEngine.js

@@ -53,7 +53,7 @@ define([
 	 *    must be forwarded to all other remote peers. The suggested interval
 	 *    for calling this method is every ten seconds.
 	 *
-	 *  - void syncInbound(state):
+	 *  - void syncInbound(site, state):
 	 *    Applications should call this method when they receive a remote
 	 *    peer's internal engine state (the context vector returned from the
 	 *    remote peer's syncOutbound call).

README.markdown

@@ -3,19 +3,27 @@
 ##About
 
 This project contains the JavaScript source for the operational transformation
-(OT) engine.
+(OT) engine. The OT engine is exposed as a library for application programmers
+who wish to build collaborative groupware applications.
 
-The OT engine is exposed as a library for application programmers who wish to
-build collaborative groupware applications.
+The OT API is built using Asynchronous Module Definitions (AMD) so that it can
+easily be used with any toolkit that supports AMD loading (eg. Dojo). The OT API
+can also be used with Node.js with the requirejs module for loading the OT
+library.
 
 ##Usage
 
+###Getting the code
+
 Application programmers wishing to use the OT API can checkout this project as a
 git repository (or submodule into an already existing git repository), or
 download the code as a tarball and extract into their project.
 
+###API usage
+
 Each participating *peer* has its own instance of an operation engine. Each peer
-maintains its own local copy of the collaborative data.
+maintains its own local copy of the collaborative data (there is no centrally
+located copy of the data).
 
 The engine is exposed through the use of two primary mechanisms: applying
 local/remote operations and sending/retrieving engine internal data structures.
@@ -26,10 +34,56 @@ to a local copy of the data.
 
 ##Requirements
 
-This OT API library does not provide a mechanism to communicate directly with
-remote peers. Thus, the application programmer is responsible for the
-communication mechanism (eg. hosting a central server to ferry data between
-clients).
+This OT library provides only the
+[operational transform](http://en.wikipedia.org/wiki/Operational_transformation)
+algorithms and exposure to the engine. Communication between remote clients is
+not provided by this library. Thus, the application programmer is responsible
+for the communication mechanism (eg. hosting a central server to ferry data
+between clients).
+
+Example code is provided that creates a Node.js
+server for remote clients to communicate and exchange data, but this is purely
+for demonstration purposes.
+
+###Site Ids
+
+All participating peers must have a unique *site Id* assigned to them. This site
+Id must be an integer value in the range [0, 2^32-1] that can safely be
+represented by all undering agents. The safest and easiest way to assign site
+Ids is with a central server. It is recommended that a counter be used to assign
+increasing Ids starting from zero.
+
+###Total order
+
+The underlying engine algorithm requires that all operations be totally ordered.
+The simplest way to achieve this is for a central entity to arbitrarily provide
+this. For example, the OpenCoweb project has a central server append a unique
+integer to each operation before it sends the operations to other peers.
+
+No two operations should ever be considered *equal*. Even if two operations
+match identically, they should be assigned unique orders. Thus, the total order
+requirement imposed by the OT engine is a little different from the set theory
+total order, since no two elements may be equal.
+
+For optimal engine performance, the total order should be *close* to the
+temporal order that peers generate operations.
+
+###Syncing engine state
+
+Each peer's operation engine maintains an internal data structure that tracks
+each peer's internal engine state. Thus, periodically, peers must distribute
+their local engine state to remote peers. In this and other documents, the
+internal state is sometimes referred to as the engine's *context vector*. The OT
+API provides two methods for this: `syncOutBound` and `syncInBound`.
+
+`syncOutBound` takes no arguments and returns a JSON encodable object. This
+object must be sent to other peers in its exact state.
+
+`syncInBound` takes two arguments, the integer site Id of the remote peer whose
+engine state we are syncing and the remote engine state itself.
+
+It is recommended that each peer distributes its local engine state to remote
+peers every **ten** seconds.
 
 ##OpenCoweb
 This library was initially started as a part of the

examples/node.js

@@ -1,13 +1,29 @@
 
-/* TODO doc */
+/**
+ * NodeJS does not support CommonJS Asynchronous Module Definitions, but the
+ * operation engine API is built using AMDs. In order to use the OT API with
+ * NodeJS, we must use the requirejs module.
+ *
+ * We set `define' in the global namespace to requirejs's define function so
+ * that the OT API code can use it.
+ *
+ */
 var requirejs = require("requirejs");
 var define = requirejs.define;
 
 requirejs.config({
 	nodeRequire : require,
-	baseUrl : "/Users/ibmcoop/dev/jsoe",
+	baseUrl : "../",
 	paths : {
-		"coweb/jsoe" : "/Users/ibmcoop/dev/jsoe"
+		"coweb/jsoe" : "./"
 	}
 });
 
+requirejs([
+	"OTEngine"
+], function(OTEngine) {
+	var ot = new OTEngine(0);
+	console.log(ot.createOp("topic", 1,2,3));
+	/* If we get here, then everything worked correctly. */
+});
+