Extract a few more standalone manual sections from extended workflow

6 files changed, 217 insertions, 218 deletions

diff --git a/doc/debugging.md b/doc/debugging.md
new file mode 100644
index 00000000..918e3c8c
--- /dev/null
+++ b/doc/debugging.md
@@ -0,0 +1,55 @@
+### Debugging
+
+The debugger can be invoked in several ways, the simplest one is to type
+<kbd>C-u C-M-x</kbd>. This will take the current top-level form, place as many
+breakpoints inside it as possible (instrument it), and then evaluate it a
+normal. Whenever a breakpoint is reached, you'll be shown the value and asked
+for input (see below). Note that if the current form is a `defn`, it will stay
+instrumented, so the debugger will be triggered every time the function is
+called. To uninstrument `defn` (or similar forms), you just have to evaluate it
+again as you'd normally do (e.g. with <kbd>C-M-x</kbd>).
+
+Another way to trigger the debugger is by placing breakpoints yourself. Just
+write `#break` before a form, and the debugger will popup every time that form is
+evaluated. For instance, if you hit <kbd>C-M-x</kbd> on the following, a
+breakpoint is triggered every time `(inspector msg)` is evaluated.
+
+```clojure
+(defn eval-msg [{:keys [inspect] :as msg}]
+  (if inspect
+    #break (inspector msg)
+    msg))
+```
+
+Instead of `#break` you can also write `#dbg` before a form, this will not only
+breakpoint the form but also everything inside it. In the example above, this
+places a breakpoint around `(inspector msg)` and another around `msg`. If you've
+been paying attention, you may have noticed that the first option (<kbd>C-u
+C-M-x</kbd>) is a quick way of evaluating the current top-level form with `#dbg`
+in front.
+
+At any point, you can bring up a list of all currently instrumented `def`s with
+the command `cider-browse-instrumented-defs`. Protocols and types can be
+instrumented as well, but they will not be listed by this command.
+
+#### Keys
+
+`cider-debug` tries to be consistent with
+[Edebug](http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html). So
+it makes available the following bindings while stepping through code.
+
+Keyboard shortcut               | Description
+--------------------------------|-------------------------------
+<kbd>n</kbd> | Next step
+<kbd>c</kbd> | Continue without stopping
+<kbd>o</kbd> | Move out of the current sexp (like `up-list`)
+<kbd>i</kbd> | Inject a value into running code
+<kbd>e</kbd> | Eval code in current context
+<kbd>l</kbd> | Inspect local variables
+<kbd>s</kbd> | Show the current stack
+<kbd>h</kbd> | Skip all sexps up to “here” (current position). Move the cursor before doing this.
+<kbd>q</kbd> | Quit execution
+
+In addition, all the usual evaluation commands (such as <kbd>C-x C-e</kbd> or
+<kbd>C-c M-:</kbd>) will use the current lexical context (local variables) while
+the debugger is active.
diff --git a/doc/extended_workflow.md b/doc/extended_workflow.md
index ade314d8..05672862 100644
--- a/doc/extended_workflow.md
+++ b/doc/extended_workflow.md
@@ -58,164 +58,6 @@ Keyboard shortcut                       | Description
 <kbd>M-SPC</kbd>                        | Jump to previous page in paginated view
 <kbd>s</kbd>                            | Set a new page size in paginated view
 
-### Running tests
-
-You can run `clojure.test` tests pretty quickly in CIDER. Pressing <kbd>C-c C-t
-n</kbd> or <kbd>C-c C-t C-n</kbd> in a source buffer or a REPL buffer will run
-the tests for the namespace you're currently in. CIDER is smart enough to figure
-out the namespace containing the tests. 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 loaded
-**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.
-
-All test commands are available in REPL buffers as well. There you can also use
-<kbd>,</kbd> there to invoke some of the testing commands.
-
-In the buffer displaying the test execution results (`*cider-test-results*`)
-you'll have a bit of additional functionality at your disposal.
-
-Keyboard shortcut               | Description
---------------------------------|-------------------------------
-<kbd>C-c C-t t</kbd> <br/> <kbd>C-c C-t C-t</kbd> | Run test at point.
-<kbd>C-c C-t n</kbd> <br/> <kbd>C-c C-t C-n</kbd> | Run tests for current namespace.
-<kbd>C-c C-t l</kbd> <br/> <kbd>C-c C-t C-l</kbd> | Run tests for all loaded namespaces.
-<kbd>C-c C-t p</kbd> <br/> <kbd>C-c C-t C-p</kbd> | Run tests for all project namespaces. This loads the additional namespaces.
-<kbd>C-c C-t r</kbd> <br/> <kbd>C-c C-t C-r</kbd> | Re-run test failures/errors.
-<kbd>M-p</kbd>                  | Move point to previous test.
-<kbd>M-n</kbd>                  | Move point to next test.
-<kbd>t</kbd> or <kbd>M-.</kbd>  | Jump to test definition.
-<kbd>d</kbd>                    | Display diff of actual vs expected.
-<kbd>e</kbd>                    | Display test error cause and stacktrace info.
-
-Certain aspects of the test execution behavior are configurable:
-
-* If your tests are not following the `some.ns-test` naming convention you can
-customize the variable `cider-test-infer-test-ns`. It should be bound to a
-function that takes the current namespace and returns the matching test
-namespace (which may be the same as the current namespace).
-
-* If you want to view the test report regardless of whether the tests have
-passed or failed:
-
-```el
-(setq cider-test-show-report-on-success t)
-```
-
-#### Running tests automatically (test-driven development)
-
-CIDER provides a minor-mode that automatically runs all tests for a namespace
-whenever you load a file (with <kbd>C-c C-k</kbd>). You can toggle it
-manually with <kbd>M-x</kbd> `cider-auto-test-mode`, or you can use:
-
-```el
-(cider-auto-test-mode 1)
-```
-
-This is completely equivalent to manually typing <kbd>C-c C-t C-n</kbd> every
-time you load a Clojure buffer. Also, as described above before, CIDER is smart
-enough to figure out the namespace containing the tests.
-
-#### Using cider-test with alternative test libraries
-
-The `clojure.test` machinery is designed to be pluggable. Any test library
-can implement it if so desired, and therefore leverage `cider-test`. For
-instance, [test.check](https://github.com/clojure/test.check/) does this, and
-`cider-test` handles `defspec` just like `deftest`.
-
-As a test framework author, supporting the built-in `clojure.test` machinery
-(and hence `cider-test`) is pretty straightforward:
-
-1. Assoc each test fn as `:test` metadata on some var. These are what get run.
-2. Implement the `clojure.test/report` multimethod to capture the test results.
-
-The `test.check` library is a good example here. It was also designed completely
-independently of `clojure.test`. It just adds compatibility in this
-[namespace](https://github.com/clojure/test.check/blob/24f74b83f1c7a032f98efdcc1db9d74b3a6a794d/src/main/clojure/clojure/test/check/clojure_test.cljc).
-
-### Navigating stacktraces
-
-CIDER comes with a powerful solution to the problem of verbose Clojure
-stacktraces.  Stacktraces are presented in a special major mode
-(`cider-stacktrace-mode`), which gives you the possibility to filter out certain
-stack frames and some handy ways to navigate causes.  You'll also be able to go
-to the code in question with a single keystroke.
-
-Keyboard shortcut                    | Description
--------------------------------------|-------------------------------
-<kbd>M-p</kbd>                       | Move point to previous cause
-<kbd>M-n</kbd>                       | Move point to next cause
-<kbd>M-.</kbd> or <kbd>Return</kbd>  | Navigate to the source location (if available) for the stacktrace frame
-<kbd>Tab</kbd>                       | Cycle current cause detail
-<kbd>0</kbd> or <kbd>S-Tab</kbd>     | Cycle all cause detail
-<kbd>1</kbd>                         | Cycle cause #1 detail
-<kbd>2</kbd>                         | Cycle cause #2 detail
-<kbd>3</kbd>                         | Cycle cause #3 detail
-<kbd>4</kbd>                         | Cycle cause #4 detail
-<kbd>5</kbd>                         | Cycle cause #5 detail
-<kbd>j</kbd>                         | Toggle display of java frames
-<kbd>c</kbd>                         | Toggle display of clj frames
-<kbd>r</kbd>                         | Toggle display of repl frames
-<kbd>t</kbd>                         | Toggle display of tooling frames (e.g. compiler, nREPL middleware)
-<kbd>d</kbd>                         | Toggle display of duplicate frames
-<kbd>a</kbd>                         | Toggle display of all frames
-
-You can configure whether the error buffer with stacktraces should be automatically
-shown on error. By default it will be displayed, but you can change this:
-
-```el
-(setq cider-show-error-buffer nil)
-```
-
-At times, the error being displayed will originate from a bug in the
-CIDER code itself. These internal errors might frequently occur and
-interrupt your workflow, but you might not want to suppress **all**
-stacktrace buffers via the `cider-show-error-buffer` variable as
-above; instead, you might only want to suppress *this specific type*
-of internal error. The stacktrace buffers provide such an option when
-displaying an internal error. A toggle button will be displayed with
-the error type's name, and you can toggle whether this particular type
-of error will cause the stacktrace buffer to automatically show
-itself.  The toggle button controls this behavior only during the
-current Emacs session, but if you would like to make the suppression
-more permanent, you can do so by customizing the
-`cider-stacktrace-suppressed-errors` variable.  The buffer will also
-provide a direct link to the bug reporting page to help facilitate its
-diagnosis and repair.
-
-Independently of the value of `cider-show-error-buffer` or `cider-stacktrace-suppressed-errors`,
-the error buffer is always generated in the background. Use `cider-visit-error-buffer` to visit
-this buffer.
-
-There are two more selective strategies for the error buffer:
-
-```el
-(setq cider-show-error-buffer 'except-in-repl) ; or
-(setq cider-show-error-buffer 'only-in-repl)
-```
-
-* To disable auto-selection of the error buffer when it's displayed:
-
-```el
-(setq cider-auto-select-error-buffer nil)
-```
-
-* Error buffer stacktraces may be filtered by default. Valid filter types
-include `java`, `clj`, `repl`, `tooling`, and `dup`. Setting this to `nil` will
-show all stacktrace frames.
-
-```el
-(setq cider-stacktrace-default-filters '(tooling dup))
-```
-
-* Error messages may be wrapped for readability. If this value is nil, messages
-will not be wrapped; if it is truthy but non-numeric, the default `fill-column`
-will be used.
-
-```el
-(setq cider-stacktrace-fill-column 80)
-```
-
 ### Enlighten (display local values)
 
 This feature displays the value of locals in realtime, as your code is being
@@ -240,62 +82,6 @@ and reevaluate the definitions you had instrumented previously.
 You can also trigger this on specific functions (without having to turn on the
 minor mode) by writing `#light` before the `(def` and reevaluating it.
 
-### Debugging
-
-The debugger can be invoked in several ways, the simplest one is to type
-<kbd>C-u C-M-x</kbd>. This will take the current top-level form, place as many
-breakpoints inside it as possible (instrument it), and then evaluate it a
-normal. Whenever a breakpoint is reached, you'll be shown the value and asked
-for input (see below). Note that if the current form is a `defn`, it will stay
-instrumented, so the debugger will be triggered every time the function is
-called. To uninstrument `defn` (or similar forms), you just have to evaluate it
-again as you'd normally do (e.g. with <kbd>C-M-x</kbd>).
-
-Another way to trigger the debugger is by placing breakpoints yourself. Just
-write `#break` before a form, and the debugger will popup every time that form is
-evaluated. For instance, if you hit <kbd>C-M-x</kbd> on the following, a
-breakpoint is triggered every time `(inspector msg)` is evaluated.
-
-```clojure
-(defn eval-msg [{:keys [inspect] :as msg}]
-  (if inspect
-    #break (inspector msg)
-    msg))
-```
-
-Instead of `#break` you can also write `#dbg` before a form, this will not only
-breakpoint the form but also everything inside it. In the example above, this
-places a breakpoint around `(inspector msg)` and another around `msg`. If you've
-been paying attention, you may have noticed that the first option (<kbd>C-u
-C-M-x</kbd>) is a quick way of evaluating the current top-level form with `#dbg`
-in front.
-
-At any point, you can bring up a list of all currently instrumented `def`s with
-the command `cider-browse-instrumented-defs`. Protocols and types can be
-instrumented as well, but they will not be listed by this command.
-
-#### Keys
-
-`cider-debug` tries to be consistent with
-[Edebug](http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html). So
-it makes available the following bindings while stepping through code.
-
-Keyboard shortcut               | Description
---------------------------------|-------------------------------
-<kbd>n</kbd> | Next step
-<kbd>c</kbd> | Continue without stopping
-<kbd>o</kbd> | Move out of the current sexp (like `up-list`)
-<kbd>i</kbd> | Inject a value into running code
-<kbd>e</kbd> | Eval code in current context
-<kbd>l</kbd> | Inspect local variables
-<kbd>s</kbd> | Show the current stack
-<kbd>h</kbd> | Skip all sexps up to “here” (current position). Move the cursor before doing this.
-<kbd>q</kbd> | Quit execution
-
-In addition, all the usual evaluation commands (such as <kbd>C-x C-e</kbd> or
-<kbd>C-c M-:</kbd>) will use the current lexical context (local variables) while
-the debugger is active.
-
 ### Code reloading
 
 `cider-refresh` wraps
diff --git a/doc/index.md b/doc/index.md
index a7b38efc..c1331769 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -56,19 +56,19 @@ CIDER packs plenty of features. Here are some of them (in no particular order):
 * [Powerful REPL](using_the_repl.md)
 * [Interactive code evaluation](interactive_programming.md)
 * Compilation notes (error and warning highlighting)
-* [Human-friendly stacktraces](extended_workflow.md#navigating-stacktraces)
-* [Smart code completion](configuration.md#auto-completion)
+* [Human-friendly stacktraces](navigating_stacktraces.md)
+* [Smart code completion](code_completion.md)
 * Definition lookup
 * Documentation lookup
 * Resource lookup
 * Apropos
-* [Debugger](extended_workflow.md#debugging)
+* [Debugger](debugging.md)
 * [Value inspector](extended_workflow.md#value-inspection)
 * Function tracing
 * [Interactive macroexpansion](extended_workflow.md#macroexpansion)
 * Enhanced Clojure font-locking and indentation
 * [Grimoire](http://conj.io/) integration
-* [`clojure.test` integration](extended_workflow.md#running-tests)
+* [`clojure.test` integration](running-tests.md)
 * [Smart code reloading](extended_workflow.md#code-reloading)
 * [Pretty-printing of results](configuration.md#pretty-printing)
 * Classpath browser
diff --git a/doc/navigating_stacktraces.md b/doc/navigating_stacktraces.md
new file mode 100644
index 00000000..d90d0e89
--- /dev/null
+++ b/doc/navigating_stacktraces.md
@@ -0,0 +1,82 @@
+### Navigating stacktraces
+
+CIDER comes with a powerful solution to the problem of verbose Clojure
+stacktraces.  Stacktraces are presented in a special major mode
+(`cider-stacktrace-mode`), which gives you the possibility to filter out certain
+stack frames and some handy ways to navigate causes.  You'll also be able to go
+to the code in question with a single keystroke.
+
+Keyboard shortcut                    | Description
+-------------------------------------|-------------------------------
+<kbd>M-p</kbd>                       | Move point to previous cause
+<kbd>M-n</kbd>                       | Move point to next cause
+<kbd>M-.</kbd> or <kbd>Return</kbd>  | Navigate to the source location (if available) for the stacktrace frame
+<kbd>Tab</kbd>                       | Cycle current cause detail
+<kbd>0</kbd> or <kbd>S-Tab</kbd>     | Cycle all cause detail
+<kbd>1</kbd>                         | Cycle cause #1 detail
+<kbd>2</kbd>                         | Cycle cause #2 detail
+<kbd>3</kbd>                         | Cycle cause #3 detail
+<kbd>4</kbd>                         | Cycle cause #4 detail
+<kbd>5</kbd>                         | Cycle cause #5 detail
+<kbd>j</kbd>                         | Toggle display of java frames
+<kbd>c</kbd>                         | Toggle display of clj frames
+<kbd>r</kbd>                         | Toggle display of repl frames
+<kbd>t</kbd>                         | Toggle display of tooling frames (e.g. compiler, nREPL middleware)
+<kbd>d</kbd>                         | Toggle display of duplicate frames
+<kbd>a</kbd>                         | Toggle display of all frames
+
+You can configure whether the error buffer with stacktraces should be automatically
+shown on error. By default it will be displayed, but you can change this:
+
+```el
+(setq cider-show-error-buffer nil)
+```
+
+At times, the error being displayed will originate from a bug in the
+CIDER code itself. These internal errors might frequently occur and
+interrupt your workflow, but you might not want to suppress **all**
+stacktrace buffers via the `cider-show-error-buffer` variable as
+above; instead, you might only want to suppress *this specific type*
+of internal error. The stacktrace buffers provide such an option when
+displaying an internal error. A toggle button will be displayed with
+the error type's name, and you can toggle whether this particular type
+of error will cause the stacktrace buffer to automatically show
+itself.  The toggle button controls this behavior only during the
+current Emacs session, but if you would like to make the suppression
+more permanent, you can do so by customizing the
+`cider-stacktrace-suppressed-errors` variable.  The buffer will also
+provide a direct link to the bug reporting page to help facilitate its
+diagnosis and repair.
+
+Independently of the value of `cider-show-error-buffer` or `cider-stacktrace-suppressed-errors`,
+the error buffer is always generated in the background. Use `cider-visit-error-buffer` to visit
+this buffer.
+
+There are two more selective strategies for the error buffer:
+
+```el
+(setq cider-show-error-buffer 'except-in-repl) ; or
+(setq cider-show-error-buffer 'only-in-repl)
+```
+
+* To disable auto-selection of the error buffer when it's displayed:
+
+```el
+(setq cider-auto-select-error-buffer nil)
+```
+
+* Error buffer stacktraces may be filtered by default. Valid filter types
+include `java`, `clj`, `repl`, `tooling`, and `dup`. Setting this to `nil` will
+show all stacktrace frames.
+
+```el
+(setq cider-stacktrace-default-filters '(tooling dup))
+```
+
+* Error messages may be wrapped for readability. If this value is nil, messages
+will not be wrapped; if it is truthy but non-numeric, the default `fill-column`
+will be used.
+
+```el
+(setq cider-stacktrace-fill-column 80)
+```
diff --git a/doc/running_tests.md b/doc/running_tests.md
new file mode 100644
index 00000000..d69ac972
--- /dev/null
+++ b/doc/running_tests.md
@@ -0,0 +1,74 @@
+### Running tests
+
+You can run `clojure.test` tests pretty quickly in CIDER. Pressing <kbd>C-c C-t
+n</kbd> or <kbd>C-c C-t C-n</kbd> in a source buffer or a REPL buffer will run
+the tests for the namespace you're currently in. CIDER is smart enough to figure
+out the namespace containing the tests. 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 loaded
+**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.
+
+All test commands are available in REPL buffers as well. There you can also use
+<kbd>,</kbd> there to invoke some of the testing commands.
+
+In the buffer displaying the test execution results (`*cider-test-results*`)
+you'll have a bit of additional functionality at your disposal.
+
+Keyboard shortcut               | Description
+--------------------------------|-------------------------------
+<kbd>C-c C-t t</kbd> <br/> <kbd>C-c C-t C-t</kbd> | Run test at point.
+<kbd>C-c C-t n</kbd> <br/> <kbd>C-c C-t C-n</kbd> | Run tests for current namespace.
+<kbd>C-c C-t l</kbd> <br/> <kbd>C-c C-t C-l</kbd> | Run tests for all loaded namespaces.
+<kbd>C-c C-t p</kbd> <br/> <kbd>C-c C-t C-p</kbd> | Run tests for all project namespaces. This loads the additional namespaces.
+<kbd>C-c C-t r</kbd> <br/> <kbd>C-c C-t C-r</kbd> | Re-run test failures/errors.
+<kbd>M-p</kbd>                  | Move point to previous test.
+<kbd>M-n</kbd>                  | Move point to next test.
+<kbd>t</kbd> or <kbd>M-.</kbd>  | Jump to test definition.
+<kbd>d</kbd>                    | Display diff of actual vs expected.
+<kbd>e</kbd>                    | Display test error cause and stacktrace info.
+
+Certain aspects of the test execution behavior are configurable:
+
+* If your tests are not following the `some.ns-test` naming convention you can
+customize the variable `cider-test-infer-test-ns`. It should be bound to a
+function that takes the current namespace and returns the matching test
+namespace (which may be the same as the current namespace).
+
+* If you want to view the test report regardless of whether the tests have
+passed or failed:
+
+```el
+(setq cider-test-show-report-on-success t)
+```
+
+#### Running tests automatically (test-driven development)
+
+CIDER provides a minor-mode that automatically runs all tests for a namespace
+whenever you load a file (with <kbd>C-c C-k</kbd>). You can toggle it
+manually with <kbd>M-x</kbd> `cider-auto-test-mode`, or you can use:
+
+```el
+(cider-auto-test-mode 1)
+```
+
+This is completely equivalent to manually typing <kbd>C-c C-t C-n</kbd> every
+time you load a Clojure buffer. Also, as described above before, CIDER is smart
+enough to figure out the namespace containing the tests.
+
+#### Using cider-test with alternative test libraries
+
+The `clojure.test` machinery is designed to be pluggable. Any test library
+can implement it if so desired, and therefore leverage `cider-test`. For
+instance, [test.check](https://github.com/clojure/test.check/) does this, and
+`cider-test` handles `defspec` just like `deftest`.
+
+As a test framework author, supporting the built-in `clojure.test` machinery
+(and hence `cider-test`) is pretty straightforward:
+
+1. Assoc each test fn as `:test` metadata on some var. These are what get run.
+2. Implement the `clojure.test/report` multimethod to capture the test results.
+
+The `test.check` library is a good example here. It was also designed completely
+independently of `clojure.test`. It just adds compatibility in this
+[namespace](https://github.com/clojure/test.check/blob/24f74b83f1c7a032f98efdcc1db9d74b3a6a794d/src/main/clojure/clojure/test/check/clojure_test.cljc).
diff --git a/mkdocs.yml b/mkdocs.yml
index f1a5588d..a9436608 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -9,6 +9,8 @@ pages:
 - Interactive Programming: interactive_programming.md
 - Using the REPL: using_the_repl.md
 - Code Completion: code_completion.md
+- Running Tests: running_tests.md
+- Debugging: debugging.md
 - Extended Workflow: extended_workflow.md
 - Configuration: configuration.md
 - Indentation Specification: indent_spec.md