Improve general doc (#3333)

autoload/SpaceVim.vim

@@ -1150,6 +1150,8 @@ function! SpaceVim#end() abort
     " Navigation in command line
     cnoremap <C-a> <Home>
     cnoremap <C-b> <Left>
+    " @bug_vim with <silent> command line can not be cleared
+    cnoremap <expr> <C-k> repeat('<Delete>', strchars(getcmdline()) - getcmdpos() + 1)
   endif
   call SpaceVim#server#connect()
 

autoload/SpaceVim/default.vim

@@ -259,7 +259,7 @@ function! SpaceVim#default#keyBindings() abort
   " Tabs
   nnoremap <silent>g0 :<C-u>tabfirst<CR>
   nnoremap <silent>g$ :<C-u>tablast<CR>
-  nnoremap <silent>gr :<C-u>tabprevious<CR>
+  nnoremap <silent><expr> gr tabpagenr('#') > 0 ? ':exe "tabnext " . tabpagenr("#")<cr>' : ''
 
   " Remove spaces at the end of lines
   nnoremap <silent> ,<Space> :<C-u>silent! keeppatterns %substitute/\s\+$//e<CR>

autoload/SpaceVim/layers/core.vim

@@ -282,18 +282,19 @@ function! SpaceVim#layers#core#config() abort
   "
   " Toggles the comment state of the selected line(s). If the topmost selected
   " line is commented, all selected lines are uncommented and vice versa.
+  nnoremap <silent> <Plug>CommentToLine :call <SID>comment_to_line(0)<Cr>
+  nnoremap <silent> <Plug>CommenterInvertYank :call <SID>comment_invert_yank()<Cr>
+  nnoremap <silent> <Plug>CommentToLineInvert :call <SID>comment_to_line(1)<Cr>
+  nnoremap <silent> <Plug>CommentParagraphs :call <SID>comment_paragraphs(0)<Cr>
+  nnoremap <silent> <Plug>CommentParagraphsInvert :call <SID>comment_paragraphs(1)<Cr>
   call SpaceVim#mapping#space#def('nmap', ['c', 'l'], '<Plug>NERDCommenterInvert', 'toggle-comment-lines', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', 'L'], '<Plug>NERDCommenterComment', 'comment-lines', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', 'u'], '<Plug>NERDCommenterUncomment', 'uncomment-lines', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', 'v'], '<Plug>NERDCommenterInvertgv', 'toggle-visual-comment-lines', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', 's'], '<Plug>NERDCommenterSexy', 'comment-with-sexy-layout', 0, 1)
+  call SpaceVim#mapping#space#def('nmap', ['c', 'y'], '<Plug>CommenterInvertYank', 'yank-and-toggle-comment', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', 'Y'], '<Plug>NERDCommenterYank', 'yank-and-comment', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', '$'], '<Plug>NERDCommenterToEOL', 'comment-from-cursor-to-end-of-line', 0, 1)
-
-  nnoremap <silent> <Plug>CommentToLine :call <SID>comment_to_line(0)<Cr>
-  nnoremap <silent> <Plug>CommentToLineInvert :call <SID>comment_to_line(1)<Cr>
-  nnoremap <silent> <Plug>CommentParagraphs :call <SID>comment_paragraphs(0)<Cr>
-  nnoremap <silent> <Plug>CommentParagraphsInvert :call <SID>comment_paragraphs(1)<Cr>
   call SpaceVim#mapping#space#def('nmap', ['c', 't'], '<Plug>CommentToLineInvert', 'toggle-comment-until-line', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', 'T'], '<Plug>CommentToLine', 'comment-until-the-line', 0, 1)
   call SpaceVim#mapping#space#def('nmap', ['c', 'p'], '<Plug>CommentParagraphsInvert', 'toggle-comment-paragraphs', 0, 1)
@@ -713,6 +714,15 @@ function! s:comment_to_line(invert) abort
   endif
 endfunction
 
+function! s:comment_invert_yank() abort
+  if mode() ==# 'n'
+    normal! yy
+  elseif mode() ==? 'v'
+    normal! y
+  endif
+  call feedkeys("\<Plug>NERDCommenterInvert")
+endfunction
+
 function! s:better_easymotion_overwin_line(is_visual) abort
   let current_line = line('.')
   try

docs/documentation.md

@@ -10,6 +10,7 @@ description: "General documentation about how to using SpaceVim, including the q
 - [Core Pillars](#core-pillars)
 - [Highlighted features](#highlighted-features)
 - [Screenshots](#screenshots)
+- [Concepts](#concepts)
 - [Who can benefit from this?](#who-can-benefit-from-this)
 - [Update and Rollback](#update-and-rollback)
   - [Update SpaceVim itself](#update-spacevim-itself)
@@ -20,7 +21,6 @@ description: "General documentation about how to using SpaceVim, including the q
   - [Vim compatible mode](#vim-compatible-mode)
   - [Private Layers](#private-layers)
   - [Debug upstream plugins](#debug-upstream-plugins)
-- [Concepts](#concepts)
 - [Interface elements](#interface-elements)
   - [Colorschemes](#colorschemes)
   - [Font](#font)
@@ -28,6 +28,8 @@ description: "General documentation about how to using SpaceVim, including the q
   - [Statusline](#statusline)
   - [Tabline](#tabline)
 - [General Key bindings](#general-key-bindings)
+  - [Visual mode key bindings](#visual-mode-key-bindings)
+  - [Command line mode key bidnings](#command-line-mode-key-bidnings)
   - [Window manager](#window-manager)
   - [File Operations](#file-operations)
   - [Editor UI](#editor-ui)
@@ -39,8 +41,6 @@ description: "General documentation about how to using SpaceVim, including the q
     - [Getting help](#getting-help)
     - [Available layers](#available-layers)
     - [Toggles](#toggles)
-  - [Navigating](#navigating)
-    - [Point/Cursor](#pointcursor)
     - [Vim motions with vim-easymotion](#vim-motions-with-vim-easymotion)
       - [quick-jump-link mode (TODO)](#quick-jump-link-mode-todo)
     - [Unimpaired bindings](#unimpaired-bindings)
@@ -105,19 +105,27 @@ If any of these core pillars is violated open an issue and we’ll try our best
 
 **Mnemonic**
 
-Key bindings are organized using mnemonic prefixes like b for buffer, p for project, s for search, h for help, etc…
+Key bindings are organized using mnemonic prefixes,
+like b for buffer, p for project, s for search, h for help,
+etc…
 
 **Discoverable**
 
-Innovative real-time display of available key bindings. Simple query system to quickly find available layers, packages, and more.
+Innovative real-time display of available key bindings.
+Simple query system to quickly find available layers,
+packages, and more.
 
 **Consistent**
 
-Similar functionalities have the same key bindings everywhere thanks to a clearly defined set of conventions. Documentation is mandatory for any layer that ships with SpaceVim.
+Similar functionalities have the same key bindings
+everywhere thanks to a clearly defined set of conventions.
+Documentation is mandatory for any layer that ships with
+SpaceVim.
 
 **Crowd-Configured**
 
-Community-driven configuration provides curated packages tuned by power users and bugs are fixed quickly.
+Community-driven configuration provides curated
+packages tuned by power users and bugs are fixed quickly.
 
 ## Highlighted features
 
@@ -134,11 +142,11 @@ Community-driven configuration provides curated packages tuned by power users an
 
 **welcome page**
 
-![welcome-page](https://user-images.githubusercontent.com/13142418/45254913-e1e17580-b3b2-11e8-8983-43d6c358a474.png)
+![welcome-page](https://user-images.githubusercontent.com/13142418/68079142-904e4280-fe1f-11e9-993e-b834ea3d39ea.png)
 
 **working flow**
 
-![screen shot 2017-04-26 at 4 28 07 pm](https://cloud.githubusercontent.com/assets/296716/25455341/6af0b728-2a9d-11e7-9721-d2a694dde1a8.png)
+![work-flow](https://cloud.githubusercontent.com/assets/296716/25455341/6af0b728-2a9d-11e7-9721-d2a694dde1a8.png)
 
 Neovim on iTerm2 using the SpaceVim color scheme _base16-solarized-dark_
 
@@ -148,6 +156,22 @@ Non-code buffers show a Neovim terminal, a TagBar window, a Vimfiler window and
 
 To get more screenshots, see: [issue #415](https://github.com/SpaceVim/SpaceVim/issues/415)
 
+## Concepts
+
+**Transient-states**
+
+SpaceVim defines a wide variety of transient states (temporary overlay maps)
+where it makes sense. This prevents one from doing repetitive and tedious
+presses on the SPC key.
+
+When a transient state is active, a documentation is displayed in the
+transient state buffer. Additional information may as well be displayed in it.
+
+Move Text Transient State:
+
+![Move Text Transient State](https://user-images.githubusercontent.com/13142418/28489559-4fbc1930-6ef8-11e7-9d5a-716fe8dbb881.png)
+
+
 ## Who can benefit from this?
 
 - **Elementary** Vim users.
@@ -164,9 +188,18 @@ There are several methods of updating the core files of SpaceVim. It is recommen
 
 **Automatic Updates**
 
-NOTE: By default, this feature is disabled. It would slow down the startup of Vim/Neovim. If you like this feature, add `automatic_update = 1` to your custom configuration file.
+By default, this feature is disabled.
+It would slow down the startup of Vim/Neovim.
+If you like this feature,
+add following to your custom configuration file.
 
-SpaceVim will automatically check for a new version every startup. You have restart Vim after updating.
+```toml
+[options]
+    automatic_update = true
+```
+
+SpaceVim will automatically check for a new version
+every startup. You have restart Vim after updating.
 
 **Updating from the SpaceVim Buffer**
 
@@ -180,11 +213,16 @@ You can close Vim/Neovim and update the git repository to update manually:
 
 ### Update plugins
 
-Use `:SPUpdate` command to update all the plugins and SpaceVim itself. After `:SPUpdate`, you can assign plugins need to be updated. Use `Tab` to complete plugin names after `:SPUpdate`.
+Use `:SPUpdate` command to update all the plugins and
+SpaceVim itself. After `:SPUpdate`, you can assign
+plugins need to be updated. Use `Tab` to complete
+plugin names after `:SPUpdate`.
 
 ### Get SpaceVim log
 
-Use `:SPDebugInfo!` command to display the log of SpaceVim. You also can use `SPC h I` to open a buffer with the issue template.
+Use `:SPDebugInfo!` command to display the log of SpaceVim.
+You also can use `SPC h I` to open a buffer with the
+issue template.
 
 ## Custom Configuration
 
@@ -229,7 +267,10 @@ If you want to disable plugins which are added by SpaceVim, you can use SpaceVim
 
 ### Bootstrap Functions
 
-SpaceVim provides two kinds of bootstrap functions for custom configurations and key bindings, namely `bootstrap_before` and `bootstrap_after`. To enable them you need to add `bootstrap_before = "myspacevim#before"` and/or `bootstrap_after = "myspacevim#after"` to `[options]` section in file `.SpaceVim.d/init.toml`. The difference is that these two functions will be called before or after the loading of SpaceVim's main scripts as they named.
+SpaceVim provides two kinds of bootstrap functions
+for custom configurations and key bindings,
+namely `bootstrap_before` and `bootstrap_after`.
+To enable them you need to add `bootstrap_before = "myspacevim#before"` and/or `bootstrap_after = "myspacevim#after"` to `[options]` section in file `.SpaceVim.d/init.toml`. The difference is that these two functions will be called before or after the loading of SpaceVim's main scripts as they named.
 
 The bootstrap functions should be placed to the `autoload` directory in `runtimepath`, please refer to `:h autoload-functions` for further instructions. In our case, create file `.SpaceVim.d/autoload/myspacevim.vim` with contents for example
 
@@ -335,21 +376,6 @@ function! myspacevim#before() abort
 endfunction
 ```
 
-## Concepts
-
-**Transient-states**
-
-SpaceVim defines a wide variety of transient states (temporary overlay maps)
-where it makes sense. This prevents one from doing repetitive and tedious
-presses on the SPC key.
-
-When a transient state is active, a documentation is displayed in the
-transient state buffer. Additional information may as well be displayed in it.
-
-Move Text Transient State:
-
-![Move Text Transient State](https://user-images.githubusercontent.com/13142418/28489559-4fbc1930-6ef8-11e7-9d5a-716fe8dbb881.png)
-
 ## Interface elements
 
 SpaceVim has a minimalistic and distraction free UI:
@@ -611,7 +637,8 @@ tabs will be listed on the tabline. Each item can be quickly accessed by using
 | `<Leader> 8` | Jump to index 8 on tabline |
 | `<Leader> 9` | Jump to index 9 on tabline |
 
-SpaceVim tabline also supports mouse click, left mouse button will switch to buffer, while middle button will delete the buffer.
+SpaceVim tabline also supports mouse click, left mouse button will switch to buffer,
+while middle button will delete the buffer.
 
 **NOTE:** This feature is only supported in Neovim with `has('tablineat')`.
 
@@ -639,6 +666,59 @@ Key bindings within tab manager windows:
 
 ## General Key bindings
 
+The following key bindings are the general key bindings for moving cursor.
+
+| Key Bindings     | Descriptions                                      |
+| ---------------- | ------------------------------------------------- |
+| `h`              | move cursor left                                  |
+| `j`              | move cursor down                                  |
+| `k`              | move cursor up                                    |
+| `l`              | move cursor right                                 |
+| `<Up>`, `<Down>` | Smart up and down                                 |
+| `H`              | move cursor to the top of the screen              |
+| `L`              | move cursor to the bottom of the screen           |
+| `<`              | Indent to left and re-select                      |
+| `>`              | Indent to right and re-select                     |
+| `}`              | paragraphs forward                                |
+| `{`              | paragraphs backward                               |
+| `Ctrl-f`         | Smart page forward (`Ctrl-f` / `Ctrl-d`)          |
+| `Ctrl-b`         | Smart page backward (`C-b` / `C-u`)               |
+| `Ctrl-e`         | Smart scroll down (`3 Ctrl-e/j`)                  |
+| `Ctrl-y`         | Smart scroll up (`3Ctrl-y/k`)                     |
+| `Ctrl-c`         | Copy full path of current buffer to X11 clipboard |
+
+### Visual mode key bindings
+
+| Key               | Action                                   |
+| ----------------- | ---------------------------------------- |
+| `<Leader> y`      | Copy selection to X11 clipboard ("+y)    |
+| `<Leader> p`      | Paste selection from X11 clipboard ("+p) |
+| `<`               | Indent to left and re-select             |
+| `>`               | Indent to right and re-select            |
+| `<Tab>`           | Indent to right and re-select            |
+| `Shift-<Tab>`     | Indent to left and re-select             |
+| `Ctrl-q`          | `Ctrl-w`                                 |
+| `Ctrl-x`          | Switch buffer and placement              |
+| `Ctrl-Shift-Up`   | move lines up                            |
+| `Ctrl-Shift-Down` | move lines down                          |
+
+### Command line mode key bidnings
+
+After pressing `:`, you can switch to comamnd line mode, here is a list of key bindings
+can be used in command line mode:
+
+| Key bindings   | Descriptions                         |
+| -------------- | ------------------------------------ |
+| `Ctrl-a`       | move cursor to beginning             |
+| `Ctrl-b`       | Move cursor backward in command line |
+| `Ctrl-f`       | Move cursor forward in command line  |
+| `Ctrl-w`       | delete a whole word                  |
+| `Ctrl-u`       | remove all text before cursor        |
+| `Ctrl-k`       | remove all text after cursor         |
+| `Ctrl-c`/`Esc` | cancel command line mode             |
+| `Tab`          | next item in popup menu              |
+| `Shift-Tab`    | previous item in popup menu          |
+
 ### Window manager
 
 Window manager key bindings can only be used in normal mode. The default leader `[WIN]` is `s`, you
@@ -667,31 +747,6 @@ can change it via `windows_leader` option:
 SpaceVim has mapped normal `q` as smart buffer close, the normal func of `q`
 can be get by `<Leader> q r`, if you want to disable this feature, you can use `vimcompatible` mode.
 
-| Key               | Mode          | Action                                                                         |
-| ----------------- | ------------- | ------------------------------------------------------------------------------ |
-| `<Leader> y`      | visual        | Copy selection to X11 clipboard ("+y)                                          |
-| `Ctrl-c`          | Normal        | Copy full path of current buffer to X11 clipboard                              |
-| `<Leader> Ctrl-c` | Normal        | Copy github.com url of current buffer to X11 clipboard(if it is a github repo) |
-| `<Leader> Ctrl-l` | Normal/visual | Copy github.com url of current lines to X11 clipboard(if it is a github repo)  |
-| `<Leader> p`      | Normal/visual | Paste selection from X11 clipboard ("+p)                                       |
-| `Ctrl-f`          | Normal        | Smart page forward (`Ctrl-f` / `Ctrl-d`)                                       |
-| `Ctrl-b`          | Normal        | Smart page backwards (`C-b` / `C-u`)                                           |
-| `Ctrl-e`          | Normal        | Smart scroll down (`3 Ctrl-e/j`)                                               |
-| `Ctrl-y`          | Normal        | Smart scroll up (`3Ctrl-y/k`)                                                  |
-| `Ctrl-q`          | Normal        | `Ctrl-w`                                                                       |
-| `Ctrl-x`          | Normal        | Switch buffer and placement                                                    |
-| `<Up>`, `<Down>`  | Normal        | Smart up and down                                                              |
-| `}`               | Normal        | After paragraph motion go to first non-blank char (}^)                         |
-| `<`               | Visual/Normal | Indent to left and re-select                                                   |
-| `>`               | Visual/Normal | Indent to right and re-select                                                  |
-| `<Tab>`           | Visual        | Indent to right and re-select                                                  |
-| `Shift-<Tab>`     | Visual        | Indent to left and re-select                                                   |
-| `g p`             | Normal        | Select last paste                                                              |
-| `Q` / `g Q`       | Normal        | Disable EX-mode (<Nop>)                                                        |
-| `Ctrl-a`          | Command       | Navigation in command line                                                     |
-| `Ctrl-b`          | Command       | Move cursor backward in command line                                           |
-| `Ctrl-f`          | Command       | Move cursor forward in command line                                            |
-
 ### File Operations
 
 | Key Bindings | Descriptions                    |
@@ -907,24 +962,6 @@ All plugins can be easily discovered via `<leader> l p`.
 
 Both the toggles mappings start with `[SPC] t` or `[SPC] T`. You can find them in the mapping guide.
 
-### Navigating
-
-#### Point/Cursor
-
-Navigation is performed using the Vi key bindings `hjkl`.
-
-| Key Bindings | Descriptions                                                                      |
-| ------------ | --------------------------------------------------------------------------------- |
-| `h`          | move cursor left (origin Vim key, no mappings)                                    |
-| `j`          | move cursor down (origin Vim key, no mappings)                                    |
-| `k`          | move cursor up (origin Vim key, no mappings)                                      |
-| `l`          | move cursor right (origin Vim key, no mappings)                                   |
-| `H`          | move cursor to the top of the screen (origin Vim key, no mappings)                |
-| `L`          | move cursor to the bottom of the screen (origin Vim key, no mappings)             |
-| `SPC j 0`    | go to the beginning of line (and set a mark at the previous location in the line) |
-| `SPC j $`    | go to the end of line (and set a mark at the previous location in the line)       |
-| `SPC t -`    | lock the cursor at the center of the screen                                       |
-
 #### Vim motions with vim-easymotion
 
 ##### quick-jump-link mode (TODO)
@@ -1257,6 +1294,7 @@ which will tell you the functional of all mappings starting with `g`.
 | `g m`        | go to middle of screenline                      |
 | `g n`        | visually select next match                      |
 | `g o`        | goto byte N in the buffer                       |
+| `g p`        | Select last paste                               |
 | `g s`        | sleep N seconds                                 |
 | `g t`        | next tag page                                   |
 | `g u`        | make motion text lowercase                      |