Merge pull request #60 from jdhao/doc

update setup doc

docs/README.md

@@ -2,9 +2,44 @@ This doc summarizes how to install and use this configuration in detail.
 
 # Pre-requisite
 
+## Terminal emulators
+
+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
+
+Since statusline or file explorer plugins often use Unicode symbols not available in normal font,
+we need to install a patched font from the [nerd-fonts](https://github.com/ryanoasis/nerd-fonts) project.
+
+# Automatic installation
+
+## Automatic Installation for Linux
+
+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.
+
+## Automatic installation for Windows
+
+Run script [nvim_setup_windows.ps1](nvim_setup_windows.ps1) under PowerShell.
+
+# Manual install
+
 There are a few dependencies if we want to use Nvim for efficient editing and development work.
 
-## Python
+## Dependencies
+
+### Python
 
 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).
@@ -12,7 +47,7 @@ The easiest way to install is via [Anaconda](https://docs.anaconda.com/anaconda/
 After installation, make sure that you can run `python --version`,
 and that the output should be Python 3.x.
 
-## Pynvim
+### Pynvim
 
 Nvim relies on [pynvim](https://github.com/neovim/pynvim) to communicate with plugins that utilize its Python binding.
 Pynvim is required by plugins such as [wilder.nvim](https://github.com/gelguy/wilder.nvim).
@@ -21,7 +56,7 @@ Pynvim is required by plugins such as [wilder.nvim](https://github.com/gelguy/wi
 pip install -U pynvim
 ```
 
-## python-lsp-server
+### python-lsp-server
 
 [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.
 
@@ -33,7 +68,7 @@ Note the executable for pylsp is also named `pylsp`. You need to set its PATH co
 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
+### Node
 
 We need to install node.js from [here](https://nodejs.org/en/download/).
 For Linux, you can use the following script:
@@ -60,7 +95,7 @@ source ~/.bash_profile
 # source ~/.zshrc
 ```
 
-## vim-language-server
+### 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:
 
@@ -70,7 +105,7 @@ npm install -g vim-language-server
 
 vim-language-server is installed in the same directory as the node executable.
 
-## Git
+### Git
 
 Git is required by plugin manager [packer.nvim](https://github.com/wbthomason/packer.nvim) and other git-related plugins.
 
@@ -79,7 +114,7 @@ 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
+### ctags
 
 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.
@@ -102,7 +137,7 @@ choco install universal-ctags
 
 Set its PATH properly and make sure you can run `ctags` from command line.
 
-## Ripgrep
+### Ripgrep
 
 [Ripgrep](https://github.com/BurntSushi/ripgrep), aka, `rg`, is a fast grepping tool available for both Linux, Windows and macOS.
 It is used by several searching plugins.
@@ -112,7 +147,7 @@ For Linux, we can download the [binary release](https://github.com/BurntSushi/ri
 
 Set its PATH properly and make sure you can run `rg` from command line.
 
-## Linters
+### Linters
 
 A linter is a tool to check the source code for possible style and syntax issues.
 Based on the programming languages we use, we may need to install various linters.
@@ -122,35 +157,18 @@ Based on the programming languages we use, we may need to install various linter
 
 Set their PATH properly and make sure you can run `pylint`, `flake8` and `vint` from command line.
 
-## Terminal emulators
+## Install 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
-
-Since statusline or file explorer plugins often use Unicode symbols not available in normal font,
-we need to install a patched font from the [nerd-fonts](https://github.com/ryanoasis/nerd-fonts) project.
-
-# Install Nvim
 
 There are various ways to install Nvim depending on your system.
 This config is only maintained for [the latest nvim stable release](https://github.com/neovim/neovim/releases/tag/stable).
 
-## Linux
+### Linux
 
 You 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 the latest version may not be available.
 
-## Windows
+### Windows
 
 You may download from [nvim release](https://github.com/neovim/neovim/releases/download/stable/nvim-win64.zip) from GitHub and manually extract it.
 
@@ -164,7 +182,7 @@ choco install neovim
 # scoop install neovim
 ```
 
-## macOS
+### macOS
 
 It is recommended to install neovim via [Homebrew](https://brew.sh/) on macOS. Simply run the following command:
 
@@ -175,9 +193,11 @@ brew install neovim
 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
+## Setting up Nvim
 
-## Install plugin manager packer.nvim
+After installing nvim and all the dependencies, we will install plugin managers and set up this config.
+
+### Install plugin manager packer.nvim
 
 I use packer.nvim to manage my plugins. We need to install packer.nvim on our system first.
 
@@ -193,7 +213,7 @@ For macOS and Linux, run the following command:
 git clone --depth=1 https://github.com/wbthomason/packer.nvim ~/.local/share/nvim/site/pack/packer/opt/packer.nvim
 ```
 
-## How to install this configuration
+### How to install this configuration
 
 On Linux and macOS, the directory is `~/.config/nvim`.
 On Windows, the config directory is `$HOME/AppData/Local/nvim`[^1].
@@ -207,18 +227,4 @@ 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.
 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 [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.
-
-## Automatic installation for Windows
-
-Run script [nvim_setup_windows.ps1](nvim_setup_windows.ps1) under PowerShell.
-
 [^1]: Use `echo %userprofile%` to see where your `$HOME` is.