From b8cb61a0e1fa40337a10b3dad48c0f5c9f21359f Mon Sep 17 00:00:00 2001 From: Wang Shidong Date: Wed, 6 May 2020 20:59:34 +0800 Subject: [PATCH] Update doc (#3507) --- autoload/SpaceVim.vim | 85 +++++++++++++++------- autoload/SpaceVim/plugins/tasks.vim | 4 ++ doc/SpaceVim.txt | 108 +++++++++++++++++++--------- 3 files changed, 140 insertions(+), 57 deletions(-) diff --git a/autoload/SpaceVim.vim b/autoload/SpaceVim.vim index 29ad56331..d82b986e3 100644 --- a/autoload/SpaceVim.vim +++ b/autoload/SpaceVim.vim @@ -10,7 +10,7 @@ " @section Introduction, intro " @stylized spacevim " @library -" @order intro options config layers api faq changelog +" @order intro options config layers usage api faq changelog " SpaceVim is a bundle of custom settings and plugins with a modular " configuration for Vim. It was inspired by Spacemacs. " @@ -947,6 +947,16 @@ let g:spacevim_windows_smartclose = 'q' " let g:spacevim_disabled_plugins = ['vim-foo', 'vim-bar'] " < let g:spacevim_disabled_plugins = [] +"" +" @section custom_plugins, usage-custom_plugins +" @parentsection usage +" Add custom plugins. +" > +" [[custom_plugins]] +" name = 'vimwiki/vimwiki' +" merged = false +" < + "" " Add custom plugins. " > @@ -1365,16 +1375,18 @@ function! SpaceVim#welcome() abort endif endfunction +"" +" @section Usage, usage +" the usage guide for SpaceVim + "" " @section FAQ, faq -"1. How do I enable YouCompleteMe? -" > -" I do not recommend using YouCompleteMe. -" It is too big as a vim plugin. Also, I do not like using submodules in a vim -" plugin. It is hard to manage with a plugin manager. +" This is a list of the frequently asked questions about SpaceVim. " -" Step 1: Add `let g:spacevim_enable_ycm = 1` to custom_config. By default -" it should be `~/.SpaceVim.d/init.vim`. +" 1. How do I enable YouCompleteMe? +" +" Step 1: Add `enable_ycm = true` to custom_config. By default it should be +" `~/.SpaceVim.d/init.toml`. " " Step 2: Get into the directory of YouCompleteMe's author. By default it " should be `~/.cache/vimfiles/repos/github.com/Valloric/`. If you find the @@ -1385,40 +1397,65 @@ endfunction " " Step 3: Compile YouCompleteMe with the features you want. If you just want " C family support, run `./install.py --clang-completer`. -" < +" " " 2. How to add custom snippet? -" > -" SpaceVim uses neosnippet as the default snippet engine. If you want to add -" a snippet for a vim filetype, open a vim file and run `:NeoSnippetEdit` -" command. A buffer will be opened and you can add your custom snippet. -" By default this buffer will be save in `~/.SpaceVim/snippets`. -" If you want to use another directory: +" +" SpaceVim uses neosnippet as the default snippet engine. This can be changed +" by @section(options-snippet_engine) option. " -" let g:neosnippet#snippets_directory = '~/path/to/snip_dir' +" If you want to add a snippet for a current filetype, run |:NeoSnippetEdit| +" command. A buffer will be opened and you can add your custom snippet. +" By default this buffer will be save in `~/.SpaceVim.d/snippets`. +" +" For more info about how to write snippet, please +" read |neosnippet-snippet-syntax|. " -" For more info about how to write snippet, please -" read |neosnippet-snippet-syntax|. -" < " " 3. Where is `` in cmdline-mode? -" > +" " `` is the default value of |cedit| option, but in SpaceVim we use that -" binding as ``, so maybe you can change the `cedit` option or use +" binding as ``, so maybe you can change the `cedit` option or use " `+`. -" < " " 4. How to use `` as ``? +" +" Add `let g:mapleader = "\"` to bootstrap function. +" +" 5. Why does Vim freeze after pressing Ctrl-s? +" +" This is a feature of terminal emulators. You can use `Ctrl-q` to unfreeze Vim. To disable +" this feature you need the following in either `~/.bash_profile` or `~/.bashrc`: +"> +" stty -ixon +"< +" +" 6. How to enable `+py` and `+py3` in Neovim? +" +" In Neovim we can use `g:python_host_prog` and `g:python3_host_prog` +" to config python prog. But in SpaceVim the custom configuration file is +" loaded after SpaceVim core code. So in SpaceVim itself, if we using `:py` +" command, it may cause errors. +" +" So we introduce two new environment variables: `PYTHON_HOST_PROG` and +" `PYTHON3_HOST_PROG`. +" +" For example: " > -" Add `let mapleader = "\"` to `~/.SpaceVim.d/init.vim` +" export PYTHON_HOST_PROG='/home/q/envs/neovim2/bin/python' +" export PYTHON3_HOST_PROG='/home/q/envs/neovim3/bin/python' " < "" " @section Changelog, changelog -" Following HEAD: changes in master branch since last release v1.3.0 +" Following HEAD: changes in master branch since last release v1.4.0 " " https://github.com/SpaceVim/SpaceVim/wiki/Following-HEAD " +" 2020-04-05: v1.4.0 +" +" https://spacevim.org/SpaceVim-release-v1.4.0/ +" " 2019-11-04: v1.3.0 " " https://spacevim.org/SpaceVim-release-v1.3.0/ diff --git a/autoload/SpaceVim/plugins/tasks.vim b/autoload/SpaceVim/plugins/tasks.vim index 20943a479..126343712 100644 --- a/autoload/SpaceVim/plugins/tasks.vim +++ b/autoload/SpaceVim/plugins/tasks.vim @@ -9,6 +9,10 @@ " this plugin is based on vscode task Scheme " https://code.visualstudio.com/docs/editor/tasks-appendix +"" +" @section tasks, usage-tasks +" @parentsection usage +" general guide for tasks manager in SpaceVim. let s:TOML = SpaceVim#api#import('data#toml') let s:JSON = SpaceVim#api#import('data#json') diff --git a/doc/SpaceVim.txt b/doc/SpaceVim.txt index 3ec4da235..799f54737 100644 --- a/doc/SpaceVim.txt +++ b/doc/SpaceVim.txt @@ -154,7 +154,10 @@ CONTENTS *SpaceVim-contents* 79. tmux...........................................|SpaceVim-layer-tmux| 80. tools#dash...............................|SpaceVim-layer-tools-dash| 81. tools#zeal...............................|SpaceVim-layer-tools-zeal| - 7. API........................................................|SpaceVim-api| + 7. Usage....................................................|SpaceVim-usage| + 1. custom_plugins........................|SpaceVim-usage-custom_plugins| + 2. tasks..........................................|SpaceVim-usage-tasks| + 8. API........................................................|SpaceVim-api| 1. cmdlinemenu................................|SpaceVim-api-cmdlinemenu| 2. data#dict....................................|SpaceVim-api-data-dict| 3. data#list....................................|SpaceVim-api-data-list| @@ -170,8 +173,8 @@ CONTENTS *SpaceVim-contents* 13. vim#command...............................|SpaceVim-api-vim-command| 14. vim#compatible.........................|SpaceVim-api-vim-compatible| 15. vim#message...............................|SpaceVim-api-vim-message| - 8. FAQ........................................................|SpaceVim-faq| - 9. Changelog............................................|SpaceVim-changelog| + 9. FAQ........................................................|SpaceVim-faq| + 10. Changelog...........................................|SpaceVim-changelog| ============================================================================== INTRODUCTION *SpaceVim-intro* @@ -3102,6 +3105,26 @@ TOOLS#ZEAL *SpaceVim-layer-tools-zeal* This layer provides Zeal integration for SpaceVim +============================================================================== +USAGE *SpaceVim-usage* + + the usage guide for SpaceVim + +============================================================================== +CUSTOM_PLUGINS *SpaceVim-usage-custom_plugins* + +Add custom plugins. +> + [[custom_plugins]] + name = 'vimwiki/vimwiki' + merged = false +< + +============================================================================== +TASKS *SpaceVim-usage-tasks* + +general guide for tasks manager in SpaceVim. + ============================================================================== API *SpaceVim-api* @@ -3378,63 +3401,82 @@ VIM#MESSAGE *SpaceVim-api-vim-message* ============================================================================== FAQ *SpaceVim-faq* +This is a list of the frequently asked questions about SpaceVim. + 1. How do I enable YouCompleteMe? -> - I do not recommend using YouCompleteMe. - It is too big as a vim plugin. Also, I do not like using submodules in a vim - plugin. It is hard to manage with a plugin manager. - - Step 1: Add `let g:spacevim_enable_ycm = 1` to custom_config. By default - it should be `~/.SpaceVim.d/init.vim`. + Step 1: Add `enable_ycm = true` to custom_config. By default it should be +`~/.SpaceVim.d/init.toml`. Step 2: Get into the directory of YouCompleteMe's author. By default it - should be `~/.cache/vimfiles/repos/github.com/Valloric/`. If you find the - directory `YouCompleteMe` in it, go into it. Otherwise clone - YouCompleteMe repo by - `git clone https://github.com/Valloric/YouCompleteMe.git`. After cloning, - get into it and run `git submodule update --init --recursive`. +should be `~/.cache/vimfiles/repos/github.com/Valloric/`. If you find the +directory `YouCompleteMe` in it, go into it. Otherwise clone YouCompleteMe +repo by `git clone https://github.com/Valloric/YouCompleteMe.git`. After +cloning, get into it and run `git submodule update --init --recursive`. Step 3: Compile YouCompleteMe with the features you want. If you just want - C family support, run `./install.py --clang-completer`. -< +C family support, run `./install.py --clang-completer`. + 2. How to add custom snippet? -> - SpaceVim uses neosnippet as the default snippet engine. If you want to add - a snippet for a vim filetype, open a vim file and run `:NeoSnippetEdit` - command. A buffer will be opened and you can add your custom snippet. - By default this buffer will be save in `~/.SpaceVim/snippets`. - If you want to use another directory: + SpaceVim uses neosnippet as the default snippet engine. This can be changed +by |SpaceVim-options-snippet_engine| option. - let g:neosnippet#snippets_directory = '~/path/to/snip_dir' + If you want to add a snippet for a current filetype, run |:NeoSnippetEdit| +command. A buffer will be opened and you can add your custom snippet. By +default this buffer will be save in `~/.SpaceVim.d/snippets`. + + For more info about how to write snippet, please read +|neosnippet-snippet-syntax|. - For more info about how to write snippet, please - read |neosnippet-snippet-syntax|. -< 3. Where is `` in cmdline-mode? -> `` is the default value of |cedit| option, but in SpaceVim we use that - binding as ``, so maybe you can change the `cedit` option or use - `+`. -< +binding as ``, so maybe you can change the `cedit` option or use +`+`. 4. How to use `` as ``? + Add `let g:mapleader = "\"` to bootstrap function. + + 5. Why does Vim freeze after pressing Ctrl-s? + + This is a feature of terminal emulators. You can use `Ctrl-q` to unfreeze +Vim. To disable this feature you need the following in either +`~/.bash_profile` or `~/.bashrc`: > - Add `let mapleader = "\"` to `~/.SpaceVim.d/init.vim` + stty -ixon +< + + 6. How to enable `+py` and `+py3` in Neovim? + + In Neovim we can use `g:python_host_prog` and `g:python3_host_prog` to +config python prog. But in SpaceVim the custom configuration file is loaded +after SpaceVim core code. So in SpaceVim itself, if we using `:py` command, +it may cause errors. + + So we introduce two new environment variables: `PYTHON_HOST_PROG` and +`PYTHON3_HOST_PROG`. + + For example: +> + export PYTHON_HOST_PROG='/home/q/envs/neovim2/bin/python' + export PYTHON3_HOST_PROG='/home/q/envs/neovim3/bin/python' < ============================================================================== CHANGELOG *SpaceVim-changelog* -Following HEAD: changes in master branch since last release v1.3.0 +Following HEAD: changes in master branch since last release v1.4.0 https://github.com/SpaceVim/SpaceVim/wiki/Following-HEAD +2020-04-05: v1.4.0 + +https://spacevim.org/SpaceVim-release-v1.4.0/ + 2019-11-04: v1.3.0 https://spacevim.org/SpaceVim-release-v1.3.0/