Update README.mkd

README.mkd

@@ -1,7 +1,7 @@
 shoreleave
 ==========
 
-     A smarter client-side in ClojureScript
+A smarter client-side in ClojureScript
 
 ###Shoreleave is a collection of integrated libraries that focuses on:
 
@@ -11,19 +11,81 @@ shoreleave
  * HTML5 capabilities
  * ClojureScript's advantages
 
-###Shoreleave is made up of:
+Overview
+----------
+Shoreleave has support for the following:
+
+### A remotes package
+
+Shoreleave's remotes package includes XHR, Pooled-XHR, JSONP, and HTTP-RPC capabilities.
+
+CSRF protection is built in if your Clojure server is using the [ring-anti-forgery](#) middleware.
+
+The HTTP-RPC allows for exposing a server-side namespace as a client-side API, via a single server-side call, `remote-ns`
+A typical [Noir](#) setup might look like:
+
+     (ns example
+       (:require [noir.shoreleave.rpc :as rpc]))
+     
+     ;; The Base Web Server
+     ;; ---------------------                                                                                                                                       
+     ;; Serve every view file found in `src/example/views`
+     (server/load-views "src/example/views/")
+     
+     ;; Remote Namespaces
+     ;; -----------------
+     (rpc/activate-remotes!)
+     (rpc/remote-ns 'example.api :as "api") ; Note, you don't have to include example.api in this .clj file
+     
+     ;; Middleware
+     ;;-----------
+     (server/add-middleware ring.middleware.gzip/wrap-gzip)
+     (server/add-middleware ring.middleware.file-info/wrap-file-info)
+     (server/add-middleware ring.middleware.anti-forgery/wrap-anti-forgery)
+
+
+### A pub/sub abstraction (and implementations)
+
+**Why would I ever want to use this?**
+Shoreleave's pub/sub system enables you to completely decouple parts of your app and declaritively bind them together.
+New features and functionalities can be built by composing pre-existing services/publishables.
+
+This gives you the heart of Reactive Javascript (RxJS), without the additional verbs (both a benefit and a tradeoff).
+It's often most beneficial to use DOM listeners as entry-points into the pub/sub system.
+
+Additionally you can express cross-cutting functionality (like logging or metrics reporting) as a service.
+
+- - -
+
+Shoreleave's pub/sub system is built upon two protocols: one to express "brokers" and one to express "publishables"
+
+These allow anyone to implement new brokers or buses upon JavaScript or Browser technologies,
+while also extending the system's support to any user defined types (by making them publishable).
+
+Out of the box, Shoreleave allows you to publish funtions, atoms, and anything that implements (str ...)/.toString as topics.
+The simple pub/sub bus has little overhead but will only work in single document cases.  The cross document bus has
+a small amount of overhead, but allows you to publish and subscribe from/to functions that live in other web workers
+or windows.
+
+
+### Common client-side interactions
 
- * A remotes package, with CSRF-protected XHR, Pooled-XHR, JSONP, and HTTP-RPC capabilities
-   * HTTP-RPC allows for exposing a server-side namespace as a client-side API
- * A language-wide pub/sub system - enabling declarative binding for all aspects of your client-side
-   * Functions and atoms can be `topics`, allowing one function to subscribe to another that lives in a web worker!
-   * Use any function as a client-side service (like logging!)
  * An idiomatic interface to cookies
  * An idiomatic interface to browser history (with extended support for HTML5 History API)
  * (Coming soon) An idiomatic interface to browser storage (Local Storage, Session Storage, and App Cache)
  * Common auxiliary functions out-of-the-box to handle query strings, browser-repl, hash strings, and CLJS/JS interop
- * Prepackaged services including: Google Maps and DuckDuckGo One-Click (Wikipedia and Alpha coming soon)
- * A Function object that supports metadata
+
+### Common external API support
+
+Shoreleave has JSONP-wrapped support for external APIs including:
+
+ * Google Maps
+ * DuckDuckGo One-Click
+ * (Coming soon) Wikipedia and Alpha
+
+### An enhanced the ClojureScript experience
+
+ * A `Function` object that supports metadata
  * (Coming soon) The ability to create embedded web workers
 
 Plays well with others