1 files changed, 39 insertions, 24 deletions

diff --git a/docs/user/README.md b/docs/user/README.md
index 1b2d98608..968d2e34c 100644
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -1,14 +1,19 @@
 The main interface to rust-analyzer is the
 [LSP](https://microsoft.github.io/language-server-protocol/) implementation. To
-install lsp server, use `cargo xtask install --server`, which is a shorthand for `cargo
-install --package ra_lsp_server`. The binary is named `ra_lsp_server`, you
-should be able to use it with any LSP-compatible editor. We use custom
+install lsp server, clone the repository and then run `cargo xtask install
+--server` (which is shorthand for `cargo install --path
+./crates/ra_lsp_server`). This will produce a binary named `ra_lsp_server` which
+you should be able to use it with any LSP-compatible editor. We use custom
 extensions to LSP, so special client-side support is required to take full
 advantage of rust-analyzer. This repository contains support code for VS Code
 and Emacs.
 
-Rust Analyzer needs sources of rust standard library to work, so you might need
-to execute
+```
+$ git clone [email protected]:rust-analyzer/rust-analyzer && cd rust-analyzer
+$ cargo xtask install --server
+```
+Rust Analyzer needs sources of rust standard library to work, so
+you might also need to execute
 
 ```
 $ rustup component add rust-src
@@ -133,43 +138,31 @@ Prerequisites:
 Installation:
 
 * add
-[ra-emacs-lsp.el](https://github.com/rust-analyzer/rust-analyzer/blob/69ee5c9c5ef212f7911028c9ddf581559e6565c3/editors/emacs/ra-emacs-lsp.el)
+[ra-emacs-lsp.el](../../editors/emacs/ra-emacs-lsp.el)
 to load path and require it in `init.el`
 * run `lsp` in a rust buffer
 * (Optionally) bind commands like `rust-analyzer-join-lines`, `rust-analyzer-extend-selection` and `rust-analyzer-expand-macro` to keys, and enable `rust-analyzer-inlay-hints-mode` to get inline type hints
 
 
-## Vim and NeoVim
+## Vim and NeoVim (coc-rust-analyzer)
 
-Neovim 0.5 has a built in language server. For a quick start configuration of
-rust-analyzer, use [neovim/nvim-lsp](https://github.com/neovim/nvim-lsp#rust_analyzer).
-Once `neovim/nvim-lsp` is installed, you can use `call nvim_lsp#setup("rust_analyzer", {})`
-or `lua require'nvim_lsp'.rust_analyzer.setup({})` to quickly get set up.
-
-* Install coc.nvim by following the instructions at [coc.nvim]
-  - You will need nodejs installed.
-  - You may want to include some of the sample vim configurations [from here][coc-vim-conf]
-  - Note that if you use a plugin manager other than `vim-plug`, you may need to manually
-    checkout the `release` branch wherever your plugin manager cloned it. Otherwise you will
-    get errors about a missing javascript file.
-* Run `:CocInstall coc-rust-analyzer` to install [coc-rust-analyzer], this extension implemented _most_ of the features supported in the VSCode extension:
+* Install coc.nvim by following the instructions at [coc.nvim][] (nodejs required)
+* Run `:CocInstall coc-rust-analyzer` to install [coc-rust-analyzer], this extension implements _most_ of the features supported in the VSCode extension:
   - same configurations as VSCode extension, `rust-analyzer.raLspServerPath`, `rust-analyzer.enableCargoWatchOnStartup` etc.
   - same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.startCargoWatch` etc.
   - highlighting and inlay_hints are not implemented yet
 
 [coc.nvim]: https://github.com/neoclide/coc.nvim
-[coc-vim-conf]: https://github.com/neoclide/coc.nvim/#example-vim-configuration
 [coc-rust-analyzer]: https://github.com/fannheyward/coc-rust-analyzer
 
-## Vim and NeoVim Alternative
+## Vim and NeoVim (LanguageClient-neovim)
 
 * Install LanguageClient-neovim by following the instructions [here][lang-client-neovim]
-  - No extra run-time is required as this server is written in Rust
   - The github project wiki has extra tips on configuration
 
 * Configure by adding this to your vim/neovim config file (replacing the existing rust specific line if it exists):
 
-```
+```vim
 let g:LanguageClient_serverCommands = {
 \ 'rust': ['ra_lsp_server'],
 \ }
@@ -177,6 +170,13 @@ let g:LanguageClient_serverCommands = {
 
 [lang-client-neovim]: https://github.com/autozimu/LanguageClient-neovim
 
+## NeoVim (nvim-lsp)
+
+NeoVim 0.5 (not yet released) has built in language server support. For a quick start configuration
+of rust-analyzer, use [neovim/nvim-lsp](https://github.com/neovim/nvim-lsp#rust_analyzer).
+Once `neovim/nvim-lsp` is installed, you can use `call nvim_lsp#setup("rust_analyzer", {})`
+or `lua require'nvim_lsp'.rust_analyzer.setup({})` to quickly get set up.
+
 
 ## Sublime Text 3
 
@@ -208,4 +208,19 @@ Installation:
 
 * You can now invoke the command palette and type LSP enable to locally/globally enable the rust-analyzer LSP (type LSP enable, then choose either locally or globally, then select rust-analyzer)
 
-* Note that `ra_lsp_server` binary must be in `$PATH` for this to work. If it's not the case, you can specify full path to the binary, which is typically `.cargo/bin/ra_lsp_server`.
+### Setting up the `PATH` variable
+
+On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's
+startup file. Depending on your configuration, your Desktop Environment might not
+actually load it. If you find that `rust-analyzer` only runs when starting the
+editor from the terminal, you will have to set up your `PATH` variable manually.
+
+There are a couple of ways to do that:
+
+- for Code, set `rust-analyzer.raLspServerPath` to `~/.cargo/bin` (the `~` is
+  automatically resolved by the extension)
+- copy the binary to a location that is already in `PATH`, e.g. `/usr/local/bin`
+- on Linux, use PAM to configure the `PATH` variable, by e.g. putting
+  `PATH DEFAULT=/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:@{HOME}/.cargo/bin:@{HOME}/.local/bin`
+  in your `~/.pam_environment` file; note that this might interfere with other
+  defaults set by the system administrator via `/etc/environment`.