[Fix #495] Add some ClojureScript usage documentation.

README.md

@@ -44,6 +44,7 @@ CIDER packs plenty of features. Here are some of them (in no particular order):
 - [Installation](#installation)
 	- [Prerequisites](#prerequisites)
 	- [Installation via package.el](#installation-via-packageel)
+- [ClojureScript](#clojurescript)
 - [Configuration](#configuration)
 - [Basic Usage](#basic-usage)
 	- [Setting up a Leiningen project (optional)](#setting-up-a-leiningen-project-optional)
@@ -180,6 +181,48 @@ For snapshot releases of CIDER you should use the snapshot of the plugin as well
 **Note that you need to use at least CIDER 0.7 for the nREPL middleware to work
 properly.  Don't use cider-nrepl with CIDER 0.6.**
 
+## ClojureScript
+
+ClojureScript support relies on the
+[piggieback](https://github.com/cemerick/piggieback) nREPL middleware being
+present in your REPL session. This is supported by (and is the recommended
+method for using) both the [Austin](https://github.com/cemerick/austin) and
+[Weasel](https://github.com/tomjakubowski/weasel) ClojureScript REPLs.
+
+* Example usage of a non-browser connected Austin REPL (requires
+e.g. `[com.cemerick/austin "0.1.5"]` in your project's `:plugins`):
+
+  - At the Clojure REPL:
+
+    ```clojure
+    (cemerick.piggieback/cljs-repl :repl-env (cemerick.austin/exec-env))
+    ```
+
+* Example usage of browser-connected Weasel REPL (requires e.g. `[weasel "0.4.2"]` in your project's
+`:dependencies`):
+
+  - At the Clojure REPL:
+
+    ```clojure
+    (require 'weasel.repl.websocket)
+    (cemerick.piggieback/cljs-repl :repl-env (weasel.repl.websocket/repl-env :ip "0.0.0.0" :port 9001))
+    ```
+
+  - and in your ClojureScript:
+
+    ```clojure
+    (ns my.cljs.core
+      (:require [weasel.repl :as ws-repl]))
+
+    (ws-repl/connect "ws://localhost:9001")
+    ```
+
+Provided that a Piggieback-enabled ClojureScript environment is active in your
+REPL session, code loading and evaluation will work seamlessly regardless of the
+presence of the `cider-nrepl` middleware. If the middleware is present then most
+other features of CIDER will also be enabled (including code completion,
+documentation lookup, the namespace browser, and macroexpansion).
+
 ## Configuration
 
 You can certainly use `CIDER` without configuring it any further,
@@ -755,14 +798,20 @@ change `*cider-repl localhost*` to `*cider-repl foo*`.
 
 ## Caveats
 
-### Completion
+### ClojureScript
+
+Currently, the following features are not supported for ClojureScript
+development:
+
+* Grimoire lookup
+* The inspector
+* Reloading
+* Running tests
+* Tracing
 
-ClojureScript completion is provided by the
-[cider-nrepl](https://github.com/clojure-emacs/cider-nrepl) 'complete'
-implementation middleware which relies on
-[piggieback](https://github.com/cemerick/piggieback).  Include it in
-your project middlewares and call `(cemerick.piggieback/cljs-repl)` or
-another method to start up the ClojureScript REPL.
+There is currently no support for both Clojure and ClojureScript evaluation in
+the same nREPL session. If Piggieback is active, code evaluation and all
+features will assume ClojureScript.
 
 ### Microsoft Windows