update config doc

1 files changed, 34 insertions, 21 deletions

diff --git a/docs/README.md b/docs/README.md
index c634856..d025898 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,12 +1,16 @@
+This doc summarizes how to install and use this configuration in detail.
+
 # Pre-requisite
 
 There are a few dependencies if we want to use Nvim for efficient editing and development work.
 
 ## Python
 
-A lot of Nvim plugins are mainly written in Python. To use auto-completion and other features, we must install Python 3.
-The easiest way to install is via [Anaconda](https://www.anaconda.com/distribution/#download-section) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html).
-Make sure that you can run `python --version`, and that the output should be Python 3.x.
+A lot of Nvim plugins are mainly written in Python, so we must install Python 3.
+The easiest way to install is via [Anaconda](https://docs.anaconda.com/anaconda/install/index.html) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html).
+
+After installation, make sure that you can run `python --version`,
+and that the output should be Python 3.x.
 
 ## Pynvim
 
@@ -19,15 +23,20 @@ pip install -U pynvim
 
 ## python-lsp-server
 
-[python-lsp-server](https://github.com/python-lsp/python-lsp-server) is the community-fork of [pyls](https://github.com/palantir/python-language-server), and it is a Python [Language Server](https://microsoft.github.io/language-server-protocol/) for completion, linting, go to definition, etc.
+[python-lsp-server (pylsp)](https://github.com/python-lsp/python-lsp-server) is a Python [Language Server](https://microsoft.github.io/language-server-protocol/) for completion, linting, go to definition, etc.
 
 ```
 pip install 'python-lsp-server[all]' pylsp-mypy pyls-isort
 ```
 
+Note the executable for pylsp is also named `pylsp`. You need to set its PATH correctly.
+If you use pip from Anaconda, the executable path may be something like `$CONDA_ROOT/bin/pylsp`.
+For native python, the path for pylsp may be like `$HOME/.local/bin/pylsp`
+
 ## Node
 
-We need to install node.js from [here](https://nodejs.org/en/download/):
+We need to install node.js from [here](https://nodejs.org/en/download/).
+For Linux, you can use the following script:
 
 ```bash
 # Ref: https://johnpapa.net/node-and-npm-without-sudo/
@@ -53,20 +62,21 @@ source ~/.bash_profile
 
 ## vim-language-server
 
-[vim-language-server](https://github.com/iamcco/vim-language-server) provides completion for vim script.
-We can install vim-language-server globally and set its path:
+[vim-language-server](https://github.com/iamcco/vim-language-server) provides completion for vim script. We can install vim-language-server globally:
 
 ```bash
 npm install -g vim-language-server
-
-export PATH="$HOME/.npm-packages/bin:$PATH"
 ```
 
+vim-language-server is installed in the same directory as the node executable.
+
 ## Git
 
-Git is used by the plugin manager [packer.nvim](https://github.com/wbthomason/packer.nvim) to clone plugins from Git repositories.
+Git is required by plugin manager [packer.nvim](https://github.com/wbthomason/packer.nvim) and other git-related plugins.
 
-Since Git is usually pre-installed on Linux and macOS, we do not need to worry if we are on these two platforms.
+For Linux and macOS, Git is usually pre-installed.
+The version of Git on the Linux system may be too old so that plugins may break.
+Check [here](https://jdhao.github.io/2021/03/27/upgrade_git_on_linux/) on how to install and set up the latest version of Git.
 For Windows, install [Git for Windows](https://git-scm.com/download/win) and make sure you can run `git` from command line.
 
 ## ctags
@@ -74,6 +84,7 @@ For Windows, install [Git for Windows](https://git-scm.com/download/win) and mak
 In order to use tags related plugins such as [vista.vim](https://github.com/liuchengxu/vista.vim), we need to install a ctags distribution.
 Universal-ctags is preferred.
 
+To install it on Linux, we need to build it from source. See [here](https://askubuntu.com/a/836521/768311) for the details.
 To install ctags on macOS, use [Homebrew](https://github.com/universal-ctags/homebrew-universal-ctags):
 
 ```bash
@@ -89,8 +100,6 @@ choco install universal-ctags
 # scoop install univeral-ctags
 ```
 
-To install it on Linux, we need to build it from source. See [here](https://askubuntu.com/a/836521/768311) for the details.
-
 Set its PATH properly and make sure you can run `ctags` from command line.
 
 ## Ripgrep
@@ -101,6 +110,8 @@ It is used by several searching plugins.
 For Windows and macOS, we can install it via chocolatey and homebrew respectively.
 For Linux, we can download the [binary release](https://github.com/BurntSushi/ripgrep/releases) and install it.
 
+Set its PATH properly and make sure you can run `rg` from command line.
+
 ## Linters
 
 A linter is a tool to check the source code for possible style and syntax issues.
@@ -109,16 +120,18 @@ Based on the programming languages we use, we may need to install various linter
 + Python: [pylint](https://github.com/PyCQA/pylint) and [flake8](https://github.com/PyCQA/flake8).
 + Vim script: [vint](https://github.com/Kuniwak/vint).
 
+Set their PATH properly and make sure you can run `pylint`, `flake8` and `vint` from command line.
+
 ## Terminal emulators
 
-Which [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator) we choose to use greatly affects the appearance and functionalities of Nvim.
+Which [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator) we choose to use greatly affects the appearance and features of Nvim.
 Since Nvim supports true colors, terminals that support true colors are preferred.
 For a list of terminals that support true colors, see [here](https://github.com/termstandard/colors).
 
 For macOS, we can use [kitty](https://sw.kovidgoyal.net/kitty/), [iterm2](https://www.iterm2.com/), [wezterm](https://wezfurlong.org/wezterm/) or [Alacritty](https://github.com/jwilm/alacritty).
+
 If you ssh to Linux server on Windows, I recommend [wsltty](https://github.com/mintty/wsltty) and [Cygwin](https://www.cygwin.com/),
 both of them use [mintty](https://github.com/mintty/mintty) as the terminal emulator.
-
 For the latest version of Windows 10, you can also try [Windows Terminal](https://github.com/microsoft/terminal).
 
 ## Patched Fonts
@@ -135,7 +148,7 @@ Current configuration is tested against nvim v0.6.1.
 
 We can directly download the binary release from [here](https://github.com/neovim/neovim/releases/download/stable/nvim-linux64.tar.gz).
 You can also use the system package manager to install nvim,
-but that is not reliable since lastest version may not be available.
+but that is not reliable since latest version may not be available.
 
 ## Windows
 
@@ -159,7 +172,7 @@ It is recommended to install neovim via [Homebrew](https://brew.sh/) on macOS. S
 brew install neovim
 ```
 
-After installing Nvim, we need to add the directory where the Nvim executable resides to the system
+After installing Nvim, we need to set the path to nvim correctly.
 Make sure that you can run `nvim` from the command line after all these setups.
 
 # Setting up Nvim
@@ -182,8 +195,8 @@ git clone --depth=1 https://github.com/wbthomason/packer.nvim ~/.local/share/nvi
 
 ## How to install this configuration
 
-On Windows, the config directory is `$HOME/AppData/Local/nvim`[^1].
 On Linux and macOS, the directory is `~/.config/nvim`.
+On Windows, the config directory is `$HOME/AppData/Local/nvim`[^1].
 First, we need to remove all the files under the config directory (including dot files),
 then go to this directory, and run the following command:
 
@@ -191,15 +204,15 @@ then go to this directory, and run the following command:
 git clone --depth=1 https://github.com/jdhao/nvim-config.git .
 ```
 
-After that, when we first open nvim, run command `:PackerSync` to install all the plugins and generate `packer_compiled.lua`.
+After that, when we first open nvim, run command `:PackerSync` to install all the plugins.
 Since I use quite a lot of plugins (more than 60), it may take some time to install all of them.
 
 # Automatic installation
 
 ## Automatic Installation for Linux #
 
-To set up a workable Nvim environment on Linux, I use [this bash script](nvim_setup_linux.sh) to automatically install necessary dependencies,
-Nvim itself and Nvim configs in this repo.
+To set up a workable Nvim environment on Linux,
+I use [a bash script](nvim_setup_linux.sh) to automatically install necessary dependencies, Nvim itself and configs.
 
 Note that the variable `PYTHON_INSTALLED`, `SYSTEM_PYTHON` and `ADD_TO_SYSTEM_PATH` in the script
 should be set properly based on your environment.