From a0c11087c1f37854dadd1dbeeafed9ed5594841c Mon Sep 17 00:00:00 2001
From: Michael Griffiths <mikey@cich.li>
Date: Sun, 7 Dec 2014 16:54:51 +0000
Subject: [PATCH] [Fix #495] Add some ClojureScript usage documentation.

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 52 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index f7e0cc189..e3334b347 100644
--- a/README.md
+++ b/README.md
@@ -755,14 +755,58 @@ change `*cider-repl localhost*` to `*cider-repl foo*`.
 
 ## Caveats
 
-### Completion
-
-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.
+### 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).
+
+Currently, the following features are not supported for ClojureScript
+development:
+
+* Grimoire lookup
+* The inspector
+* Reloading
+* Running tests
+* Tracing
+
+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