Extend a bit the Troubleshooting section of the manual

1 files changed, 29 insertions, 14 deletions

diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md
index ba924e88..3c5ddb9e 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.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.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`.
@@ -153,7 +168,7 @@ manually, as per the
 [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