Merge tag 'v0.17.0+dfsg'

DFSG-clean upstream version 0.17.0

17 files changed, 505 insertions, 254 deletions

diff --git a/doc/additional_packages.md b/doc/additional_packages.md
index 07d995c4..c4e2d8d8 100644
--- a/doc/additional_packages.md
+++ b/doc/additional_packages.md
@@ -18,13 +18,6 @@ down the road.
 **Make sure that the version of `clj-refactor` you've installed is compatible with
 your CIDER version.**
 
-## clojure-cheatsheet
-
-[clojure-cheatsheet](https://github.com/clojure-emacs/clojure-cheatsheet) in an
-Emacs rendition of the web-based
-[official Clojure Cheatsheet](http://clojure.org/api/cheatsheet), that's easily
-searchable via Helm.
-
 ## helm-cider
 
 [helm-cider](https://github.com/clojure-emacs/helm-cider) provides Helm
@@ -45,7 +38,12 @@ Flycheck checker for Clojure, using tools like
 [core.typed](http://typedclojure.org/) and
 [kibit](https://github.com/jonase/kibit).
 
-## inf-clojure
+## sayid
+
+[sayid](http://bpiel.github.io/sayid/) is a powerful alternative of CIDER's
+built-in basic tracing functionality.
+
+## Inf-clojure
 
 This package provides basic interaction with a Clojure subprocess (REPL). It's
 based on ideas from the popular inferior-lisp package.
@@ -105,14 +103,6 @@ RainbowDelimiters you can enable it in the REPL like this:
 (add-hook 'cider-repl-mode-hook #'rainbow-delimiters-mode)
 ```
 
-## auto-complete
-
-[auto-complete](http://cx4a.org/software/auto-complete/) is a popular Emacs
-interactive auto-completion
-framework. [ac-cider](https://github.com/clojure-emacs/ac-cider) provides a
-completion source for auto-complete-mode, including, where CIDER provides it,
-pop-up documentation for completed symbols.
-
 ## eval-sexp-fu
 
 [eval-sexp-fu](https://github.com/hchbaw/eval-sexp-fu.el) provides some visual
diff --git a/doc/cider-refcard.tex b/doc/cider-refcard.tex
index 7f09e249..6d877bd5 100644
--- a/doc/cider-refcard.tex
+++ b/doc/cider-refcard.tex
@@ -80,7 +80,7 @@
   \item[C-c C-k] cider-load-buffer
   \item[C-c C-l] cider-load-file
   \item[C-c C-M-l] cider-load-all-files
-  \item[C-c C-r] cider-eval-region
+  \item[C-c C-v] cider-eval-commands-map
   \item[C-c C-n] cider-eval-ns-form
   \item[C-x C-e] \ns{cider-eval-last-sexp}
   \item[C-c C-w] \ns                     -and-replace
diff --git a/doc/clojurescript.md b/doc/clojurescript.md
new file mode 100644
index 00000000..17393e09
--- /dev/null
+++ b/doc/clojurescript.md
@@ -0,0 +1,215 @@
+## ClojureScript
+
+CIDER works with ClojureScript, but you should keep in mind that not all
+the functionality available with Clojure exists for ClojureScript (at least
+not yet). To give you a concrete example - things like running tests and
+the debugger are currently Clojure-only features.
+
+ClojureScript support relies on the [piggieback][] nREPL middleware
+being present in your REPL session. There's one exception to this,
+though - [shadow-cljs][]. It has its own nREPL middleware and doesn't rely
+on piggieback at all.
+
+To setup piggieback add the following dependencies to your project
+(`project.clj` in Leiningen based project or `build.boot` in Boot
+project):
+
+```clojure
+;; use whatever are the most recent versions here
+[cider/piggieback "0.3.2"]
+[org.clojure/clojure "1.9.0"]
+```
+
+as well as `piggieback` nREPL middleware:
+
+in `project.clj`:
+
+```clojure
+:repl-options {:nrepl-middleware [cider.piggieback/wrap-cljs-repl]}
+```
+
+or in `build.boot`:
+
+```clojure
+(task-options!
+  repl {:middleware '[cider.piggieback/wrap-cljs-repl]})
+```
+
+There are many ClojureScript REPLs out there and it's often hard to wrap your
+head around them and the differences between them. You'd do well to read [this
+awesome article](https://lambdaisland.com/guides/clojure-repls/clojurescript-repls)
+before proceeding with the rest of the instructions listed here.
+
+Open a file in your project and issue <kbd>M-x</kbd>
+`cider-jack-in-clojurescript` <kbd>RET</kbd>. This will start up the nREPL
+server, and then create two REPL buffers for you, one in Clojure and one in
+ClojureScript. All usual CIDER commands will be automatically directed to the
+appropriate REPL, depending on whether you're visiting a `.clj` or a `.cljs`
+file.
+
+`cider-jack-in-clojurescript` will prompt you about the type of
+ClojureScript to start. Keep in mind that some of the REPLs will
+require some additional setup, before you can make use of them (e.g. you'll
+need to have Node.js installed to be able to start a node REPL).
+
+You can suppress the prompt the REPL to use by setting `cider-default-cljs-repl`.
+Here's an example that will make Nashorn the default:
+
+```el
+(setq cider-default-cljs-repl 'nashorn)
+```
+
+All supported ClojureScript REPLs are stored in
+`cider-cljs-repl-types`. If you need to extend it, you should use
+`cider-register-cljs-repl-type` in your Emacs configuration.
+
+```el
+(cider-register-cljs-repl-type 'super-cljs "(do (...))" optional-requirements-function)
+```
+
+You can also create a ClojureScript REPL with the command
+`cider-create-sibling-cljs-repl` in cases where you already have a
+Clojure REPL running.
+
+Continue reading for the additional setup needed for the various ClojureScript
+REPLs out there.
+
+### Browser-connected ClojureScript REPL
+
+Using Weasel, you can also have a browser-connected REPL.
+
+1. Add `[weasel "0.7.0"]` to your project's `:dependencies`.
+
+2. Issue <kbd>M-x</kbd> `cider-jack-in-clojurescript` <kbd>RET</kbd> and choose
+   the `Weasel` option when prompted about the ClojureScript REPL type you want
+   to use.
+
+3. Add this to your ClojureScript code:
+
+```clojure
+(ns my.cljs.core
+  (:require [weasel.repl :as repl]))
+(repl/connect "ws://localhost:9001")
+```
+
+4. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-clojurescript`.
+
+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).
+
+### Browser-connected ClojureScript REPL in Boot project
+
+1. Add this to your dependencies in `build.boot`:
+
+```clojure
+[adzerk/boot-cljs        "X.Y.Z"  :scope "test"]
+[adzerk/boot-cljs-repl   "X.Y.Z"  :scope "test"]
+[pandeiro/boot-http      "X.Y.Z"  :scope "test"]
+[weasel                  "0.7.0"  :scope "test"]
+[cider/piggieback "0.3.2"  :scope "test"]
+```
+
+and this at the end of `build.boot`:
+
+```clojure
+(require
+ '[adzerk.boot-cljs :refer [cljs]]
+ '[adzerk.boot-cljs-repl :refer [cljs-repl]]
+ '[pandeiro.boot-http :refer [serve]])
+
+(deftask dev []
+  (comp (serve)
+        (watch)
+        (cljs-repl) ; order is important!!
+        (cljs)))
+```
+
+2. Issue <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-boot-parameters`
+   and insert `dev`.
+
+3. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-clojurescript`.
+
+5. Connect to the running server with your browser. The address is printed on the terminal, but it's probably `http://localhost:3000`.
+
+For more information visit [boot-cljs-repl](https://github.com/adzerk-oss/boot-cljs-repl).
+
+### Using the Figwheel REPL (Leiningen-only)
+
+You can also use [Figwheel](https://github.com/bhauman/lein-figwheel) with CIDER.
+
+1. Set up Figwheel as normal, but make sure `:cljsbuild` and `:figwheel` settings are
+   in the root of your Leiningen project definition.
+
+2. Add these to your dev `:dependencies`:
+
+```clojure
+[cider/piggieback "0.3.2"]
+[figwheel-sidecar "0.5.16"] ; use here whatever the current version of figwheel is
+```
+
+Keep in mind that figwheel 0.5.16 is the first to support piggieback
+0.3. If you're using an older figwheel you should stick to piggieback
+0.2.2 (which uses the old `com.cemerick/piggieback` package coordinates).
+
+3. Add this to your dev `:repl-options`:
+
+```clojure
+:nrepl-middleware [cider.piggieback/wrap-cljs-repl]
+```
+
+4. Start the REPL with `cider-jack-in-clojurescript` (<kbd>C-c M-J</kbd>)
+
+5. Open a browser to the Figwheel URL so that it can connect to your application.
+
+You now have two nREPL connections, one for Clojure and one for ClojureScript.
+CIDER will determine which to use based on the type of file you're editing.
+
+You should also check out
+[Figwheel's wiki](https://github.com/bhauman/lein-figwheel/wiki/Using-the-Figwheel-REPL-within-NRepl).
+
+### Using shadow-cljs
+
+Provided you've configured your project correctly you can simply use
+`cider-jack-in-clojurescript` to use `shadow-cljs`.
+
+This will automatically start the shadow-cljs server and connect to it. You'll also
+be prompted for the build to use.
+
+Alternatively you can start the server manually with something like:
+
+```
+npx shadow-cljs server
+```
+
+And connect to it with `cider-connect`.
+
+[leiningen]: http://leiningen.org/
+[boot]: http://boot-clj.com/
+[piggieback]: https://github.com/clojure-emacs/piggieback
+[shadow-cljs]: https://github.com/thheller/shadow-cljs
+
+## Working with `.cljc` files
+
+Ordinarily, CIDER dispatches code from `clj` files to Clojure REPLs and `cljs`
+files to ClojureScript REPLs. However, `cljc` files have two possible connection
+targets. By default, CIDER tries to evaluate `cljc` files in all matching
+connection buffers, both `clj` and `cljs` (if present).
+
+Simply put - if you're evaluating the code `(+ 2 2)` in a `cljc` file and you
+have an active Clojure and and active ClojureScript REPL, then the code is going
+to be evaluated 2 times - once for each of them. This behavior might be a bit
+confusing, but that's what we came up with, when ruminating what was the most
+logical thing to do out-of-the-box.
+
+This can be modified with <kbd>M-x</kbd> `cider-toggle-connection-buffer`
+<kbd>RET</kbd>. Toggling this once will choose one of the connections as the
+primary, and successive calls to <kbd>M-x</kbd> `cider-toggle-connection-buffer`
+<kbd>RET</kbd> will alternate which connection to use. To restore evaluation to
+both connections, invoke `cider-toggle-connection-buffer` with a prefix argument
+(<kbd>C-u M-x</kbd> `cider-toggle-connection-buffer` <kbd>RET</kbd>).
+
+If there is only a Clojure connection, no toggling will happen and a message
+will inform you that there are no other connections to switch to.
diff --git a/doc/code_completion.md b/doc/code_completion.md
index 5973ea32..a42c08ef 100644
--- a/doc/code_completion.md
+++ b/doc/code_completion.md
@@ -1,6 +1,11 @@
 CIDER provides intelligent code completion for both source buffers (powered by
 `cider-mode`) and REPL buffers.
 
+Internally CIDER leverages
+[compliment](https://github.com/alexander-yakushev/compliment) for Clojure and
+[cljs-tooling](https://github.com/clojure-emacs/cljs-tooling) for ClojureScript.
+Improvements to the two libraries automatically translate to improvements in CIDER.
+
 ## Standard completion
 
 Out-of-the box CIDER uses the standard Emacs tooling for code completion. When you
@@ -47,9 +52,6 @@ you can add this to your config:
 (global-set-key (kbd "TAB") #'company-indent-or-complete-common)
 ```
 
-`company-indent-or-complete-common` is available only in `company-mode` 0.9+ (at
-the time of this writing it's still in development).
-
 ### Fuzzy candidate matching
 
 By default `company-mode` will provide completion candidates with the assumption
@@ -90,12 +92,3 @@ dependencies that were loaded dynamically after the REPL has started (e.g. via
 Boot). Executing `M-x cider-completion-flush-caches` (or going through the menu
 `CIDER Interaction->Misc->Flush completion cache`) forces the completion backend
 to re-read all classes it can find on the classpath.
-
-### Migrating from `auto-complete-mode`
-
-In case you have some `auto-complete-mode` configuration lying around and you
-want to switch to `company-mode` there are a few steps you have to take:
-
-* Disable `ac-cider-setup` or `ac-nrepl-setup` from running on CIDER hooks
-
-* Remove `cider-mode` and `cider-repl-mode` from the `ac-modes` list
diff --git a/doc/configuration.md b/doc/configuration.md
index c2b3477c..4cad2a1d 100644
--- a/doc/configuration.md
+++ b/doc/configuration.md
@@ -1,32 +1,43 @@
+In the spirit of Emacs almost every aspect of CIDER's behaviour
+is configurable. We've tried to come up with some reasonable
+defaults, but we've also tried to account for different people's
+preferences, so everyone could make CIDER as comfortable as
+possible for them.
+
+You can see every single customizable configuration option with the command
+<kbd>M-x customize-group RET cider</kbd>.
+
 You can certainly use CIDER without configuring it any further,
 but here are some ways other folks are adjusting their CIDER
 experience.
 
 ## Basic configuration
 
-* Suppress auto-enabling of `cider-mode` in `clojure-mode` buffers, when starting
-  CIDER:
+### Auto-enabling cider-mode in clojure-mode buffers
+
+By default CIDER will enable `cider-mode` in all `clojure-mode` buffers when the
+first CIDER connection is established. It will also add a `clojure-mode` hook to
+enable it on newly created `clojure-mode` buffers. The configuration snippet
+bellow allows you to override this (somewhat non-standard) behavior.
 
 ```el
+;; Suppress auto-enabling of `cider-mode` in `clojure-mode` buffers, when starting CIDER
 (setq cider-auto-mode nil)
 ```
 
-By default CIDER will enable `cider-mode` in all `clojure-mode` buffers when the
-first CIDER connection is established. It will also add a `clojure-mode` hook to
-enable it on newly created `clojure-mode` buffers. The configuration snippet
-above allows you to override this (somewhat non-standard) behavior.
+### Prompt for confirmation of the symbol at point
 
-* By default, interactive commands that require a symbol (e.g. `cider-doc`) will
-  prompt for the symbol, with the prompt defaulting to the symbol at point. You
-  can set `cider-prompt-for-symbol` to `nil` to instead try the command with the
-  symbol at point first, and only prompt if that fails (this used to be the
-  default behavior in older CIDER releases).
+By default, interactive commands that require a symbol (e.g. `cider-doc`) will
+prompt for the symbol, with the prompt defaulting to the symbol at point. You
+can set `cider-prompt-for-symbol` to `nil` to instead try the command with the
+symbol at point first, and only prompt if that fails (this used to be the
+default behavior in older CIDER releases).
 
 ```el
 (setq cider-prompt-for-symbol nil)
 ```
 
-* Log communication with the nREPL server:
+### Log communication with the nREPL server
 
 ```el
 (setq nrepl-log-messages t)
@@ -37,7 +48,9 @@ conn-name*`. The communication log is invaluable for debugging CIDER issues, so
 you're generally advised to enable logging when you need to debug something
 nREPL related.
 
-* You can hide the `*nrepl-connection*` and `*nrepl-server*` buffers
+### Hide special nREPL buffers
+
+You can hide the `*nrepl-connection*` and `*nrepl-server*` buffers
 from appearing in some buffer switching commands like
 `switch-to-buffer`(<kbd>C-x b</kbd>) like this:
 
@@ -49,14 +62,18 @@ When using `switch-to-buffer`, pressing <kbd>SPC</kbd> after the command will
 make the hidden buffers visible. They'll always be visible in
 `list-buffers` (<kbd>C-x C-b</kbd>).
 
-* To prefer local resources to remote (tramp) ones when both are available:
+### Prefer local resources over remote ones
+
+To prefer local resources to remote (tramp) ones when both are available:
 
 ```el
 (setq cider-prefer-local-resources t)
 ```
 
-* Prevent <kbd>C-c C-k</kbd> from prompting to save the file corresponding to
-  the buffer being loaded, if it's modified:
+### Auto-save Clojure buffers on load
+
+Normally CIDER would prompt you to save a modified Clojure buffer on <kbd>C-c C-k</kbd> (`cider-load-buffer`).
+You can change this behaviour by adjusting `cider-save-file-on-load`:
 
 ```el
 ;; Don't prompt and don't save
@@ -65,7 +82,9 @@ make the hidden buffers visible. They'll always be visible in
 (setq cider-save-file-on-load t)
 ```
 
-* Change the result prefix for interactive evaluation (by default it's `=> `):
+### Changing the result prefix for interactive evaluation
+
+Change the result prefix for interactive evaluation (by default it's `=> `):
 
 ```el
 (setq cider-eval-result-prefix ";; => ")
@@ -73,25 +92,18 @@ make the hidden buffers visible. They'll always be visible in
 
 To remove the prefix altogether just set it to an empty string(`""`).
 
-* CIDER can syntax highlight symbols that are known to be defined. By default,
-  this is done on symbols from the `clojure.core` namespace as well as macros
-  from any namespace. If you'd like CIDER to also colorize usages of functions
-  and variables from any namespace, do:
+### Use a local copy of the JDK API documentation
 
-```el
-(setq cider-font-lock-dynamically '(macro core function var))
-```
-
-* If you are targeting the JVM and prefer a local copy of the JDK API
-  documentation over Oracle's official copy (e.g., for
-  [JavaSE 8](http://docs.oracle.com/javase/8/docs/api/)), per nREPL's
-  [`javadoc-info` logic (accurate as of 29 Dec 2014)](http://docs.oracle.com/javase/8/docs/api/),
-  you can arrange your project to include the **root** path of the local API doc
-  (i.e., where the `index.html` is located) to be included on your classpath
-  (i.e., where the doc HTML files can be located by
-  `clojure.java.io/resource`). For example, for Leiningen, with the local API
-  path being `/usr/share/doc/java/api/`, put the following line in
-  `project.clj`:
+If you are targeting the JVM and prefer a local copy of the JDK API
+documentation over Oracle's official copy (e.g., for
+[JavaSE 8](http://docs.oracle.com/javase/8/docs/api/)), per nREPL's
+[`javadoc-info` logic (accurate as of 29 Dec 2014)](http://docs.oracle.com/javase/8/docs/api/),
+you can arrange your project to include the **root** path of the local API doc
+(i.e., where the `index.html` is located) to be included on your classpath
+(i.e., where the doc HTML files can be located by
+`clojure.java.io/resource`). For example, for Leiningen, with the local API
+path being `/usr/share/doc/java/api/`, put the following line in
+`project.clj`:
 
 ```clj
 :dev {:resource-paths ["/usr/share/doc/java/api/"]}
@@ -105,38 +117,116 @@ To remove the prefix altogether just set it to an empty string(`""`).
 
 More details can be found [here](https://github.com/clojure-emacs/cider/issues/930).
 
-* You can hide all nREPL middleware details from `cider-browse-ns*` and `cider-apropos*`
-  commands by customizing the variable `cider-filter-regexps`. It should be a list of
-  regexps matching the pattern of namespaces you want to filter out.
+### Use a local copy of the Java source code
+
+When an exception is thrown, e.g. when eval-ing `(. clojure.lang.RT foo)`, a
+stack trace pops up. Some places of the stack trace link to Clojure files,
+others to Java files. By default, you can click the Clojure file links to
+navigate there. If you configure `cider-jdk-src-paths`, you can also click the
+Java file links to navigate there.
+
+On Windows and macOS the JDK source code is bundled with the JDK. On Windows its
+typical location is `C:\Program Files\Java\{jdk-version}\src.zip`
+and on macOS its `/Library/Java/JavaVirtualMachines/{jdk-version}/Contents/Home/src.zip`.
+
+On Linux distributions usually the source code is distributed as a separate package.
+Here's how do get the JDK 8 source on Ubuntu:
+
+    sudo apt install openjdk-8-source
+
+The zip is installed to `/usr/lib/jvm/openjdk-8/src.zip`.
+
+You can download Clojure Java source code from
+[here](https://repo1.maven.org/maven2/org/clojure/clojure/1.8.0/clojure-1.8.0-sources.jar).
+
+Extract both and configure e.g. like so:
+
+    (setq cider-jdk-src-paths '("~/java/clojure-1.8.0-sources"
+                                "~/java/openjvm-8-src"))
+
+It's possible to use `jar` or `zip` files `cider-jdk-src-paths`, but extracting
+them is better since you get features like `ag` or `dired-jump`.
+
+### Filter out namespaces in certain namespace-related commands
 
-  Its default value is `'("^cider.nrepl" "^refactor-nrepl" "^clojure.tools.nrepl")`,
-  the most commonly used middleware collections/packages.
+You can hide all nREPL middleware details from `cider-browse-ns*` and `cider-apropos*`
+commands by customizing the variable `cider-filter-regexps`. It should be a list of
+regexps matching the pattern of namespaces you want to filter out.
 
-  An important thing to note is that this list of regexps is passed on to the middleware
-  without any pre-processing. So, the regexps have to be in Clojure format (with twice the number of backslashes)
-  and not Emacs Lisp. For example, to achieve the above effect, you could also set `cider-filter-regexps` to `'(".*nrepl")`.
+Its default value is `'("^cider.nrepl" "^refactor-nrepl" "^clojure.tools.nrepl")`,
+the most commonly used middleware collections/packages.
 
-  To customize `cider-filter-regexps`, you could use the Emacs customize UI,
-  with <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-filter-regexps`.
+An important thing to note is that this list of regexps is passed on to the middleware
+without any pre-processing. So, the regexps have to be in Clojure format (with twice the number of backslashes)
+and not Emacs Lisp. For example, to achieve the above effect, you could also set `cider-filter-regexps` to `'(".*nrepl")`.
 
-  Or by including a similar snippet along with the other CIDER configuration.
+To customize `cider-filter-regexps`, you could use the Emacs customize UI,
+with <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-filter-regexps`.
+
+Or by including a similar snippet along with the other CIDER configuration.
 
 ```el
 (setq cider-filter-regexps '(".*nrepl"))
 ```
 
-* By default contents of CIDER's special buffers such as `*cider-test-report*`
-  or `*cider-doc*` are line truncated. You can set
-  `cider-special-mode-truncate-lines` to `nil` to make those buffers use word
-  wrapping instead of line truncating.
+### Truncate long lines in special buffers
+
+By default contents of CIDER's special buffers such as `*cider-test-report*`
+or `*cider-doc*` are line truncated. You can set
+`cider-special-mode-truncate-lines` to `nil` to make those buffers use word
+wrapping instead of line truncating.
 
-  This variable should be set before loading CIDER (which means before
-  `require`-ing it or autoloading it).
+**This variable should be set before loading CIDER** (which means before
+`require`-ing it or autoloading it).
 
 ``` el
 (setq cider-special-mode-truncate-lines nil)
 ```
 
+## Syntax highlighting
+
+### Dynamic syntax highlighting
+
+CIDER can syntax highlight symbols that are known to be defined. By default,
+this is done on symbols from the `clojure.core` namespace, as well as macros
+from any namespace. If you'd like CIDER to also colorize usages of functions
+and variables from any namespace, do:
+
+```el
+(setq cider-font-lock-dynamically '(macro core function var))
+```
+
+Here's how code looks without dynamic syntax highlighting.
+
+![Dynamic Font-lock Off](images/dynamic_font_lock_off.png)
+
+And here's how to the code looks when it's turned on.
+
+![Dynamic Font-lock On](images/dynamic_font_lock_on.png)
+
+### Syntax highlighting for reader conditionals
+
+By default CIDER will apply font-locking to unused reader conditional
+expressions depending on the buffer CIDER connection type.
+
+![Reader Conditionals](images/reader_conditionals.png)
+
+You can disable this behavior by adjusting `cider-font-lock-reader-conditionals`:
+
+```el
+(setq cider-font-lock-reader-conditionals nil)
+```
+
+### Customizing CIDER faces
+
+CIDER defines a few custom faces that you might want to adjust (although normally your color theme
+should take care of them):
+
+* `cider-deprecated-face` - used for syntax highlighting deprecated vars
+* `cider-instrumented-face` - used for syntax highlighting instrumented for debugging vars
+* `cider-traced-face` - used for syntax highlighting traced vars
+* `cider-reader-conditional-face` - used for syntax highlighting inactive reader conditional branches
+
 ## Configuring eldoc
 
 * Enable `eldoc` in Clojure buffers:
@@ -246,13 +336,22 @@ are, however, ways to improve upon the standard completion if you wish to.
 (require 'icomplete)
 ```
 
+You can learn more about `icomplete`
+[here](https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html).
+
 ### ido
 
 `ido` is also bundled with Emacs and offers more features than `icomplete`.
 If you are using `ido`, be sure to use both `ido-everywhere`
-and [`ido-ubiquitous`](https://github.com/DarwinAwardWinner/ido-ubiquitous).
+and [`ido-completing-read+`](https://github.com/DarwinAwardWinner/ido-completing-read-plus).
 You might also want to install [`ido-flex`](https://github.com/lewang/flx).
 
+### ivy (recommended)
+
+If you're fine with installing a third-party package for enhanced minibuffer
+completion you can't go wrong with the modern and versatile
+[ivy](http://oremacs.com/2015/04/16/ivy-mode/).
+
 ## Pretty-printing
 
 You can configure the function used by CIDER for pretty-printing evaluation
diff --git a/doc/hacking_on_cider.md b/doc/hacking_on_cider.md
index 908e49ff..6e23fef4 100644
--- a/doc/hacking_on_cider.md
+++ b/doc/hacking_on_cider.md
@@ -71,10 +71,10 @@ $ make test
 (Note: tests may not run correctly inside Emacs' `shell-mode` buffers. Running
 them in a terminal is recommended.)
 
-You can also check for the presence of byte-compilation warnings in batch mode:
+You can also check for compliance with a variety of coding standards in batch mode (including docstrings and byte-compilation warnings):
 
 ```
-$ make test-bytecomp
+$ make lint
 ```
 
 #### Running the tests in Travis CI
@@ -179,8 +179,8 @@ pretty much anything, though. (perhaps we should change this?) To run the
 Clojure and ClojureScript tests you should specify some profile like this:
 
 ```
-$ lein with-profile +1.8,+test-clj test"
-$ lein with-profile +1.8,+test-cljs test"
+$ lein with-profile +1.8,+test-clj test
+$ lein with-profile +1.8,+test-cljs test
 ```
 
 This will run all Clojure and ClojureScript tests against version 1.8 of both
diff --git a/doc/images/dynamic_font_lock_off.png b/doc/images/dynamic_font_lock_off.png
new file mode 100644
index 00000000..e67823d6
--- /dev/null
+++ b/doc/images/dynamic_font_lock_off.png
diff --git a/doc/images/dynamic_font_lock_on.png b/doc/images/dynamic_font_lock_on.png
new file mode 100644
index 00000000..3ced2218
--- /dev/null
+++ b/doc/images/dynamic_font_lock_on.png
diff --git a/doc/images/reader_conditionals.png b/doc/images/reader_conditionals.png
new file mode 100644
index 00000000..92670c4a
--- /dev/null
+++ b/doc/images/reader_conditionals.png
diff --git a/doc/index.md b/doc/index.md
index 7d48f779..752aceda 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -74,7 +74,7 @@ CIDER packs plenty of features. Here are some of them (in no particular order):
 * nREPL session management
 * [Scratchpad](miscellaneous_features.md#using-a-scratchpad)
 * [Minibuffer code evaluation](miscellaneous_features.md#evaluating-clojure-code-in-the-minibuffer)
-* Integration with [company-mode][] and [auto-complete-mode][]
+* Integration with [company-mode][]
 * [Support for working with multiple simultaneous nREPL connections](managing_connections.md)
 
 ![CIDER Screenshot](images/cider-overview.png)
@@ -85,10 +85,9 @@ CIDER packs plenty of features. Here are some of them (in no particular order):
 [Sly]: https://github.com/capitaomorte/sly
 [Geiser]: https://github.com/jaor/geiser
 [company-mode]: http://company-mode.github.io/
-[auto-complete-mode]: https://github.com/clojure-emacs/ac-cider
 [leiningen]: http://leiningen.org/
 [boot]: http://boot-clj.com/
-[piggieback]: https://github.com/cemerick/piggieback
+[piggieback]: https://github.com/clojure-emacs/piggieback
 [vim-fireplace]: https://github.com/tpope/vim-fireplace
 [CCW]: https://github.com/laurentpetit/ccw
 [cider-nrepl]: https://github.com/clojure-emacs/cider-nrepl
diff --git a/doc/installation.md b/doc/installation.md
index 3cf6def7..79712459 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -34,7 +34,7 @@ Use the convenient plugin for defaults, either in your project's
 A minimal `profiles.clj` for CIDER would be:
 
 ```clojure
-{:repl {:plugins [[cider/cider-nrepl "0.16.0"]]}}
+{:repl {:plugins [[cider/cider-nrepl "0.17.0"]]}}
 ```
 
 **Be careful not to place this in the `:user` profile, as this way CIDER's
@@ -50,7 +50,7 @@ all of their projects using a `~/.boot/profile.boot` file like so:
 (require 'boot.repl)
 
 (swap! boot.repl/*default-dependencies*
-       concat '[[cider/cider-nrepl "0.16.0"]])
+       concat '[[cider/cider-nrepl "0.17.0"]])
 
 (swap! boot.repl/*default-middleware*
        conj 'cider.nrepl/cider-middleware)
@@ -77,6 +77,6 @@ It goes without saying that your project should depend on `cider-nrepl`.
 
 ***
 
-`x.y.z` should match the version of CIDER you're currently using (say `0.16.0`).
+`x.y.z` should match the version of CIDER you're currently using (say `0.17.0`).
 For snapshot releases of CIDER you should use the snapshot of the plugin as well
-(say `0.16.0-SNAPSHOT`).
+(say `0.17.0-SNAPSHOT`).
diff --git a/doc/interactive_programming.md b/doc/interactive_programming.md
index 815a6fd6..ba5ce55c 100644
--- a/doc/interactive_programming.md
+++ b/doc/interactive_programming.md
@@ -27,12 +27,13 @@ Here's a list of `cider-mode`'s keybindings:
 `cider-eval-defun-at-point`                   |<kbd>C-M-x</kbd> <br/> <kbd>C-c C-c</kbd>  | Evaluate the top level form under point and display the result in the echo area.
 `cider-eval-sexp-at-point`                    |<kbd>C-c C-v v</kbd>                 | Evaluate the form around point.
 `cider-eval-defun-at-point`                   |<kbd>C-u C-M-x</kbd> <br/> <kbd>C-u C-c C-c</kbd>  | Debug the top level form under point and walk through its evaluation
+`cider-eval-defun-to-point`                   |<kbd>C-c C-v z</kbd>                 | Evaluate the preceding top-level form up to the point.
 `cider-eval-region`                           |<kbd>C-c C-v r</kbd>                 | Evaluate the region and display the result in the echo area.
 `cider-interrupt`                             |<kbd>C-c C-b</kbd>                   | Interrupt any pending evaluations.
 `cider-macroexpand-1`                         |<kbd>C-c C-m</kbd>                   | Invoke `macroexpand-1` on the form at point and display the result in a macroexpansion buffer.  If invoked with a prefix argument, `macroexpand` is used instead of `macroexpand-1`.
 `cider-macroexpand-all`                       |<kbd>C-c M-m</kbd>                   | Invoke `clojure.walk/macroexpand-all` on the form at point and display the result in a macroexpansion buffer.
 `cider-eval-ns-form`                          |<kbd>C-c C-v n</kbd>                 | Eval the ns form.
-`cider-repl-set-ns`                           |<kbd>C-c M-n</kbd>                   | Switch the namespace of the REPL buffer to the namespace of the current buffer. 
+`cider-repl-set-ns`                           |<kbd>C-c M-n</kbd>                   | Switch the namespace of the REPL buffer to the namespace of the current buffer.
 `cider-switch-to-repl-buffer`                 |<kbd>C-c C-z</kbd>                   | Switch to the relevant REPL buffer. Use a prefix argument to change the namespace of the REPL buffer to match the currently visited source file.
 `cider-switch-to-repl-buffer`                 |<kbd>C-u C-u C-c C-z</kbd>           | Switch to the REPL buffer based on a user prompt for a directory.
 `cider-load-buffer-and-switch-to-repl-buffer` |<kbd>C-c M-z</kbd>                   | Load (eval) the current buffer and switch to the relevant REPL buffer. Use a prefix argument to change the namespace of the REPL buffer to match the currently visited source file.
diff --git a/doc/navigating_stacktraces.md b/doc/navigating_stacktraces.md
index e581225e..9e71f3fa 100644
--- a/doc/navigating_stacktraces.md
+++ b/doc/navigating_stacktraces.md
@@ -21,7 +21,7 @@ Command                                | Keyboard shortcut                   | D
 `cider-stacktrace-toggle-repl`         |<kbd>r</kbd>                         | Toggle display of REPL frames
 `cider-stacktrace-toggle-tooling`      |<kbd>t</kbd>                         | Toggle display of tooling frames (e.g. compiler, nREPL middleware)
 `cider-stacktrace-toggle-duplicates`   |<kbd>d</kbd>                         | Toggle display of duplicate frames
-`cider-stacktrace-show-only-project    |<kbd>p</kbd>                         | Toggle display only project frames
+`cider-stacktrace-show-only-project`   |<kbd>p</kbd>                         | Toggle display only project frames
 `cider-stacktrace-toggle-all`          |<kbd>a</kbd>                         | Toggle display of all frames
 
 You can configure whether the error buffer with stacktraces should be automatically
diff --git a/doc/running_tests.md b/doc/running_tests.md
index 29cbcfba..7baf8509 100644
--- a/doc/running_tests.md
+++ b/doc/running_tests.md
@@ -14,11 +14,24 @@ namespace that were defined with `clojure.test/with-test`)
 - in such cases you should use <kbd>C-u C-c C-t C-n</kbd>, which will simply run
 whatever tests are present in the currently visited/active namespace.
 
+You can also press <kbd>C-c C-t C-s</kbd> to run a subset of the tests defined in
+the namespace filtered by test selectors. CIDER will ask you for those test selectors
+in the minibuffer. If you call this command with a prefix (<kbd>C-u C-c C-t C-s</kbd>)
+you can suppress the inference logic as for run tests for the namespace.
+
 You can also run all loaded tests with <kbd>C-c C-t l</kbd> or <kbd>C-c C-t
 C-l</kbd> and all tests within a project with <kbd>C-c C-t p</kbd> or <kbd>C-c
 C-t C-p</kbd> (note that this will load **all** namespaces in your
-project). Using <kbd>C-c C-t t</kbd> or <kbd>C-c C-t C-t</kbd>, you can execute
-only the test a point.
+project). If you call these two with a prefix CIDER will ask for test selector filters
+and only run those tests in the project which match the selector inclusions/exclusions. Using
+<kbd>C-c C-t t</kbd> or <kbd>C-c C-t C-t</kbd>, you can execute only the
+test at point.
+
+Test selectors are originally a `leiningen` feature - see `lein help test` for some explanation.
+People use them to define subsets of tests usually run together for different purposes. For
+example you can mark some of your tests with the `^:smoke` metadata marker others with
+`^:integration`. This enables you to run these tests separately in your build pipeline.
+This feature in CIDER helps you to run these test subsets in your development environment.
 
 All test commands are available in REPL buffers as well. There you can also use
 <kbd>,</kbd> to invoke some of the testing commands.
@@ -30,6 +43,7 @@ Keyboard shortcut               | Description
 --------------------------------|-------------------------------
 <kbd>g</kbd>                    | Run test at point.
 <kbd>n</kbd>                    | Run tests for current namespace.
+<kbd>s</kbd>                    | Run tests for current namespace with selector filter.
 <kbd>l</kbd>                    | Run tests for all loaded namespaces.
 <kbd>p</kbd>                    | Run tests for all project namespaces. This loads the additional namespaces.
 <kbd>f</kbd>                    | Re-run test failures/errors.
diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md
index 982d8ddc..e29aead2 100644
--- a/doc/troubleshooting.md
+++ b/doc/troubleshooting.md
@@ -30,7 +30,22 @@ to see which command is associated with some keybinding)
 At this point you'll be dropped in the debugger and you can step forward until
 you find the problem.
 
-## REPL not starting
+## Profiling CIDER commands
+
+Emacs comes with a [built-in
+profiler](https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html). Using
+it is pretty simple:
+
+1. Start it with <kbd>M-x</kbd> `profiler-start`.
+2. Invoke some commands.
+3. Get the report with <kbd>M-x</kbd> `profiler-report`.
+
+If you intend to share the profiling results with someone it's a good idea to
+save the report buffer to a file with <kbd>C-x C-w</kbd>.
+
+## Commonly encountered problems (and how to solve them)
+
+### REPL not starting
 
 Make sure that your CIDER version matches your `cider-nrepl` version. Check
 the contents of the `*Messages*` buffer for CIDER-related errors. You should
@@ -38,20 +53,20 @@ also check the nREPL messages passed between CIDER and nREPL in
 `*nrepl-messages*`. If you don't see anything useful there it's time to bring
 out the big guns.
 
-### Debugging the REPL init
+#### Debugging the REPL init
 
 To debug CIDER's REPL initialization it's a good idea to hook into one of its
 entry points. Add a breakpoint to `cider-make-repl` (<kbd>C-u C-M-x</kbd>, while
 in its body). Next time you start CIDER you'll be dropped in the debugger and
 you can step forward until you find the problem.
 
-## Missing `*nrepl-messages*` buffer
+### Missing `*nrepl-messages*` buffer
 
 nREPL message logging is not enabled by default.  Set `nrepl-log-messages` to
 `t` to activate it. Alternatively you can use <kbd>M-x</kbd> `nrepl-toggle-message-logging`
 to enable/disable logging temporary within your current Emacs session.
 
-## `cider-debug` complains that it “failed to instrument ...”
+### `cider-debug` complains that it “failed to instrument ...”
 
 In the REPL buffer, issue the following.
 
@@ -63,7 +78,7 @@ try to debug an expression (e.g., with <kbd>C-u
 C-M-x</kbd>). [File an issue](https://github.com/clojure-emacs/cider-nrepl/issues/new)
 and copy this information.
 
-## Debugging freezes & lock-ups
+### Debugging freezes & lock-ups
 
 Sometimes a CIDER command might hang for a while (e.g. due to a bug or a
 configuration issue). Such problems are super annoying, but are relatively easy
@@ -77,7 +92,7 @@ This will bring up a backtrace with the entire function stack, including
 function arguments. So you should be able to figure out what's going on (or at
 least what's being required).
 
-## Warning saying you have to use nREPL 0.2.12+
+### Warning saying you have to use nREPL 0.2.12+
 
 CIDER currently requires at least nREPL 0.2.12 to work properly (there were some
 nasty bugs in older version and no support for tracking where some var was
@@ -99,7 +114,7 @@ Note, that running `cider-jack-in` from outside the scope of a project will
 result in the **older (0.2.6) nREPL dependency being used** (at least on Leiningen
 2.5.1). This is likely a Leiningen bug.
 
-## Missing clojure-... function after CIDER update
+### Missing clojure-... function after CIDER update
 
 Most likely you've updated CIDER, without updating `clojure-mode` as well.
 
@@ -107,7 +122,7 @@ CIDER depends on `clojure-mode` and you should always update them together, as
 the latest CIDER version might depend on functionality present only in the latest
 `clojure-mode` version.
 
-## I upgraded CIDER using `package.el` and it broke
+### I upgraded CIDER using `package.el` and it broke
 
 The built-in package manager isn't perfect and sometimes it messes up.  If you
 just updated and encountered an error you should try the following before
@@ -115,12 +130,12 @@ opening an issue: Go into the `.emacs.d/elpa` directory, delete any folders
 related to CIDER, restart Emacs and then re-install the missing packages.  Note
 that the order here matters.
 
-## I upgraded CIDER using `package.el` and nothing changed
+### I upgraded CIDER using `package.el` and nothing changed
 
 Emacs doesn't load the new files, it only installs them on disk.  To see the
 effect of changes you have to restart Emacs.
 
-## CIDER complains of the `cider-nrepl` version
+### CIDER complains of the `cider-nrepl` version
 
 This is a warning displayed on the REPL buffer when it starts, and usually looks like this:
 
@@ -129,19 +144,19 @@ This is a warning displayed on the REPL buffer when it starts, and usually looks
 where `...` might be an actual version, like `0.10.0`, or it might be `not installed` or `nil`.
 The solution to this depends on what you see and on what you're doing.
 
-### You see a number like `X.X.X`, and you're starting the REPL with `cider-connect`
+#### You see a number like `X.X.X`, and you're starting the REPL with `cider-connect`
 
 Your project specifies the wrong version for the cider-nrepl middleware. See the
-[instructions](http://cider.readthedocs.org/en/latest/installation/#ciders-nrepl-middleware)
+[instructions](http://cider.readthedocs.io/en/latest/installation/#ciders-nrepl-middleware)
 on the Installation section.
 
-### You see `not installed` or `nil`, and you're starting the REPL with `cider-connect`
+#### You see `not installed` or `nil`, and you're starting the REPL with `cider-connect`
 
 To use `cider-connect` you need to add the cider-nrepl middleware to your project. See the
-[instructions](http://cider.readthedocs.org/en/latest/installation/#ciders-nrepl-middleware)
+[instructions](http://cider.readthedocs.io/en/latest/installation/#ciders-nrepl-middleware)
 on the Installation section.
 
-### You see `not installed` or `nil`, and you're starting the REPL with `cider-jack-in`
+#### You see `not installed` or `nil`, and you're starting the REPL with `cider-jack-in`
 
 - Do `C-h v cider-inject-dependencies-at-jack-in`, and check that this variable is non-nil.
 - Make sure your project depends on at least Clojure `1.7.0`.
@@ -150,13 +165,29 @@ on the Installation section.
 
 If the above doesn't work, you can try specifying the cider-nrepl middleware
 manually, as per the
-[instructions](http://cider.readthedocs.org/en/latest/installation/#ciders-nrepl-middleware)
+[instructions](http://cider.readthedocs.io/en/latest/installation/#ciders-nrepl-middleware)
 on the Installation section.
 
-### You see a number like `X.X.X`, and you're starting the REPL with `cider-jack-in`
+#### You see a number like `X.X.X`, and you're starting the REPL with `cider-jack-in`
 
 This means you're manually adding the cider-nrepl middleware in your project,
 but you shouldn't do that because `cider-jack-in` already does that for
 you. Look into the following files, and ensure you've removed all references to
 `cider-nrepl` and `tools.nrepl`: `project.clj`, `build.boot`,
 `~/.lein/profiles.clj` and `~/.boot/profile.boot`.
+
+### I get some error related to refactor-nrepl on startup
+
+The package `clj-refactor` would normally inject its own middleware on
+`cider-jack-in`, just as CIDER itself would. Usually that's not a
+problem, as long as you're using compatible versions of CIDER and
+`clj-refactor`, but if you're getting some error probably that's not
+the case. You've got two options to solve this:
+
+* Use compatible versions of the two projects (e.g. their most recent
+  snapshots or most recent stable releases)
+* Disable the `clj-refactor` middleware injection:
+
+```el
+(setq cljr-inject-dependencies-at-jack-in nil)
+```
diff --git a/doc/up_and_running.md b/doc/up_and_running.md
index 1277638c..8098b3b3 100644
--- a/doc/up_and_running.md
+++ b/doc/up_and_running.md
@@ -76,142 +76,3 @@ helpful for identifying each host.
 ```el
 (setq cider-known-endpoints '(("host-a" "10.10.10.1" "7888") ("host-b" "7888")))
 ```
-
-## ClojureScript usage
-
-ClojureScript support relies on the [piggieback][] nREPL middleware being
-present in your REPL session.
-
-Add the following dependencies to your project (`project.clj` in Leiningen based project
-or `built.boot` in Boot project):
-
-```clojure
-[com.cemerick/piggieback "0.2.1"]
-[org.clojure/clojure "1.7.0"]
-```
-
-as well as `piggieback` nREPL middleware:
-
-in `project.clj`:
-```clojure
-:repl-options {:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]}
-```
-
-or in `built.boot`:
-```clojure
-(task-options!
-  repl {:middleware '[cemerick.piggieback/wrap-cljs-repl]})
-```
-
-Issue <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> and either
-`cider-cljs-lein-repl`, `cider-cljs-boot-repl` or `cider-cljs-gradle-repl` if
-you'd like to change the REPL used (the default is `rhino` where possible).
-
-Open a file in your project and issue <kbd>M-x</kbd>
-`cider-jack-in-clojurescript` <kbd>RET</kbd>. This will start up the nREPL
-server, and then create two REPL buffers for you, one in Clojure and one in
-ClojureScript. All usual CIDER commands will be automatically directed to the
-appropriate REPL, depending on whether you're visiting a `.clj` or a `.cljs`
-file.
-
-### Browser-connected ClojureScript REPL
-
-Using Weasel, you can also have a browser-connected REPL.
-
-1. Add `[weasel "0.7.0"]` to your project's `:dependencies`.
-
-2. Issue <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> plus either
-   `cider-cljs-lein-repl`, `cider-cljs-boot-repl` or `cider-cljs-gradle-repl`
-   and choose the `Weasel` option.
-
-3. Add this to your ClojureScript code:
-
-```clojure
-(ns my.cljs.core
-  (:require [weasel.repl :as repl]))
-(repl/connect "ws://localhost:9001")
-```
-
-4. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-clojurescript`.
-
-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).
-
-### Browser-connected ClojureScript REPL in Boot project
-
-1. Add this to your dependencies in `build.boot`:
-
-```clojure
-[adzerk/boot-cljs        "X.Y.Z"  :scope "test"]
-[adzerk/boot-cljs-repl   "X.Y.Z"  :scope "test"]
-[pandeiro/boot-http      "X.Y.Z"  :scope "test"]
-[weasel                  "0.7.0"  :scope "test"]
-[com.cemerick/piggieback "0.2.1"  :scope "test"]
-```
-
-and this at the end of `build.boot`:
-
-```clojure
-(require
- '[adzerk.boot-cljs :refer [cljs]]
- '[adzerk.boot-cljs-repl :refer [cljs-repl]]
- '[pandeiro.boot-http :refer [serve]])
-
-(deftask dev []
-  (comp (serve)
-        (watch)
-        (cljs-repl) ; order is important!!
-        (cljs)))
-```
-
-2. Issue <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-boot-parameters`
-   and insert `dev`.
-
-3. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-clojurescript`.
-
-5. Connect to the running server with your browser. The address is printed on the terminal, but it's probably `http://localhost:3000`.
-
-For more information visit [boot-cljs-repl](https://github.com/adzerk-oss/boot-cljs-repl).
-
-### Using the Figwheel REPL (Leiningen-only)
-
-You can also use [Figwheel](https://github.com/bhauman/lein-figwheel) with CIDER.
-
-1. Set up Figwheel as normal, but make sure `:cljsbuild` and `:figwheel` settings are
-   in the root of your Leiningen project definition.
-
-2. Add these to your dev `:dependencies`:
-
-```clojure
-[com.cemerick/piggieback "0.2.1"]
-[figwheel-sidecar "0.5.0-2"]
-```
-
-3. Add this to your dev `:repl-options`:
-
-```clojure
-:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]
-```
-
-4. Instruct CIDER to use Figwheel in your Emacs config:
-
-```el
-(setq cider-cljs-lein-repl "(do (use 'figwheel-sidecar.repl-api) (start-figwheel!) (cljs-repl))")
-```
-
-5. Start the REPL with `cider-jack-in-clojurescript` (<kbd>C-c M-J</kbd>)
-
-6. Open a browser to the Figwheel URL so that it can connect to your application.
-
-You now have two nREPL connections, one for Clojure and one for ClojureScript.
-CIDER will determine which to use based on the type of file you're editing.
-
-You should also check out
-[Figwheel's wiki](https://github.com/bhauman/lein-figwheel/wiki/Using-the-Figwheel-REPL-within-NRepl).
-
-[leiningen]: http://leiningen.org/
-[boot]: http://boot-clj.com/
-[piggieback]: https://github.com/cemerick/piggieback
diff --git a/doc/using_the_repl.md b/doc/using_the_repl.md
index 06ff1d3b..f240b06d 100644
--- a/doc/using_the_repl.md
+++ b/doc/using_the_repl.md
@@ -13,7 +13,7 @@ Here's a list of the keybindings that are available in CIDER's REPL:
 
 Keyboard shortcut                    | Description
 -------------------------------------|------------------------------
-<kbd>RET</kbd>        | Evaluate the current input in Clojure if it is complete. If incomplete, open a new line and indent. If invoked with a prefix argument is given then the input is evaluated without checking for completeness.
+<kbd>RET</kbd>        | Evaluate the current input in Clojure if it is complete. If incomplete, open a new line and indent. If the current input is a blank string (containing only whitespace including newlines) then clear the input without evaluating and print a fresh prompt. If invoked with a prefix argument is given then the input is evaluated without checking for completeness.
 <kbd>C-RET</kbd>      | Close any unmatched parenthesis and then evaluate the current input in Clojure.
 <kbd>C-j</kbd>        | Open a new line and indent.
 <kbd>C-c C-o</kbd>    | Remove the output of the previous evaluation from the REPL buffer. With a prefix argument it will clear the entire REPL buffer, leaving only a prompt.
@@ -208,6 +208,22 @@ To make this behavior the default:
 (setq cider-repl-use-pretty-printing t)
 ```
 
+#### Displaying images in the REPL
+
+Starting with CIDER 0.17 (Andalucía) expressions that evaluate to
+images will be rendered as images in the REPL. You can disable this
+behavior if you don't like it.
+
+```el
+(setq cider-repl-use-content-types nil)
+```
+
+Alternatively you can toggle this behaviour on and off using <kbd>M-x
+cider-repl-toggle-content-types</kbd>.
+
+Currently the feature doesn't work well with pretty-printing in the REPL,
+so you're advised not to enable both of them at the same time.
+
 #### Limiting printed output in the REPL
 
 Accidentally printing large objects can be detrimental to your
@@ -220,6 +236,38 @@ section of your Leiningen project's configuration.
 :repl-options {:init (set! *print-length* 50)}
 ```
 
+or via `cider-repl-print-length` (set to 100 by default). In case both are
+present, CIDER's config will take precedence over what came from Lein.
+
+All of this applies to `*print-level*` as well. CIDER's configuration
+variable for it is named `cider-repl-print-level` (set to `nil` by default).
+
+#### Customizing the initial REPL namespace
+
+Normally the CIDER REPL will start with the `user` namespace.
+You can supply a default value for REPL sessions via the `repl-options` section
+of your Leiningen project's configuration.
+
+```clojure
+:repl-options {:init-ns 'my-ns}
+```
+
+#### Customizing newline interaction
+
+Ordinarily <kbd>Return</kbd> sends a form for evaluation meaning entering a
+newline requires a special chord: <kbd>C-j</kbd>. When entering forms that span
+multiple lines, it may be desirable to make evaluation require the special
+invocation and have entering a new-line be the default.
+
+The following customization of the `cider-repl-mode-map` will change these
+keybindings so that <kbd>Return</kbd> will introduce a new-line and
+<kbd>C-<return></kbd> will send the form off for evaluation.
+
+``` el
+(define-key cider-repl-mode-map (kbd "RET") #'cider-repl-newline-and-indent)
+(define-key cider-repl-mode-map (kbd "C-<return>") #'cider-repl-return)
+```
+
 #### REPL history
 
 * To make the REPL history wrap around when its end is reached: