Extract a dedicated section for connection management

3 files changed, 56 insertions, 37 deletions

diff --git a/doc/index.md b/doc/index.md
index a49fc5aa..881f8e97 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -77,7 +77,7 @@ CIDER packs plenty of features. Here are some of them (in no particular order):
 * [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][]
-* [Support for working with multiple simultaneous nREPL connections](miscellaneous_features.md#managing-multiple-connections)
+* [Support for working with multiple simultaneous nREPL connections](managing_connections.md)
 
 ![CIDER Screenshot](images/cider-overview.png)
 
diff --git a/doc/managing_connections.md b/doc/managing_connections.md
new file mode 100644
index 00000000..51f5456b
--- /dev/null
+++ b/doc/managing_connections.md
@@ -0,0 +1,55 @@
+## Overview
+
+You can connect to multiple nREPL servers using <kbd>M-x</kbd> `cider-jack-in`
+(or `cider-connect`) multiple times.  To close the current nREPL connection, use
+<kbd>C-c C-q</kbd> (`cider-quit`). You can close all connections with
+<kbd>C-u C-c C-q</kbd>.
+
+CIDER maintains a list of nREPL connections and a single 'default'
+connection. When you execute CIDER commands in a Clojure editing buffer such as
+to compile a namespace, these commands are executed against a specific
+connection. This is controlled by the variable `cider-request-dispatch` - when
+it's set to `'dynamic` (the default), CIDER will try to infer which connection
+to use from the current project and currently visited file; when `'static`
+dispatch is used all requests will always be routed to the default connection
+(this was the default behavior in CIDER before 0.10).
+
+You can display the current nREPL connection using <kbd>C-c M-d</kbd>
+and rotate the default connection using <kbd>C-c M-r</kbd>. Another
+option for setting the default connection is to execute the command
+<kbd>M-x</kbd> `cider-make-connection-default` in the appropriate
+REPL buffer.
+
+## Connection browser
+
+You can obtain a list of all active connections using <kbd>M-x</kbd>
+`cider-connection-browser`. This buffer provides a few extra keybindings:
+
+Keyboard shortcut               | Description
+--------------------------------|-------------------------------
+<kbd>d</kbd>                    | Make connection at point default.
+<kbd>k</kbd>                    | Close connection at point.
+<kbd>g</kbd>                    | Refresh connection browser.
+<kbd>RET</kbd>                  | Visit connection buffer.
+<kbd>q</kbd>                    | Close window.
+
+## Switch to connection buffer
+
+The REPL buffers double as connection buffers.
+
+To switch to the relevant REPL buffer based on the Clojure namespace
+in the current Clojure buffer, use: <kbd>C-c C-z</kbd>. You can then
+use the same key combination to switch back to the Clojure buffer you
+came from.
+
+The single prefix <kbd>C-u C-c C-z</kbd>, will switch you to the
+relevant REPL buffer and set the namespace in that buffer based on
+namespace in the current Clojure buffer.
+
+## Renaming connections
+
+To change the designation used for CIDER buffers use <kbd>M-x</kbd>
+`cider-change-buffers-designation`. This changes the CIDER REPL
+buffer, nREPL connection buffer and nREPL server buffer. For example
+using `cider-change-buffers-designation` with the string "foo" would
+change `*cider-repl localhost*` to `*cider-repl foo*`.
diff --git a/doc/miscellaneous_features.md b/doc/miscellaneous_features.md
index 679f6ba3..513ace6f 100644
--- a/doc/miscellaneous_features.md
+++ b/doc/miscellaneous_features.md
@@ -185,39 +185,3 @@ Keyboard shortcut               | Description
 <kbd>^</kbd>                    | Browse all namespaces.
 <kbd>n</kbd>                    | Go to next line.
 <kbd>p</kbd>                    | Go to previos line.
-
-### Managing multiple connections
-
-You can connect to multiple nREPL servers using <kbd>M-x</kbd> `cider-jack-in`
-(or `cider-connect`) multiple times.  To close the current nREPL connection, use
-<kbd>M-x</kbd> `cider-quit`.
-
-CIDER maintains a list of nREPL connections and a single 'default'
-connection. When you execute CIDER commands in a Clojure editing buffer such as
-to compile a namespace, these commands are executed against a specific
-connection. This is controlled by the variable `cider-request-dispatch` - when
-it's set to `'dynamic` (the default), CIDER will try to infer which connection
-to use from the current project and currently visited file; when `'static`
-dispatch is used all requests will always be routed to the default connection
-(this was the default behavior in CIDER before 0.10).
-
-You can display the current nREPL connection using <kbd>C-c M-d</kbd>
-and rotate the default connection using <kbd>C-c M-r</kbd>. Another
-option for setting the default connection is to execute the command
-<kbd>M-x</kbd> `cider-make-connection-default` in the appropriate
-REPL buffer.
-
-To switch to the relevant REPL buffer based on the Clojure namespace
-in the current Clojure buffer, use: <kbd>C-c C-z</kbd>. You can then
-use the same key combination to switch back to the Clojure buffer you
-came from.
-
-The single prefix <kbd>C-u C-c C-z</kbd>, will switch you to the
-relevant REPL buffer and set the namespace in that buffer based on
-namespace in the current Clojure buffer.
-
-To change the designation used for CIDER buffers use <kbd>M-x</kbd>
-`cider-change-buffers-designation`. This changes the CIDER REPL
-buffer, nREPL connection buffer and nREPL server buffer. For example
-using `cider-change-buffers-designation` with the string "foo" would
-change `*cider-repl localhost*` to `*cider-repl foo*`.