diff options
Diffstat (limited to 'runtime/doc/usr_05.txt')
| -rw-r--r-- | runtime/doc/usr_05.txt | 133 |
1 files changed, 43 insertions, 90 deletions
diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt index 24d6185eae..076a50c582 100644 --- a/runtime/doc/usr_05.txt +++ b/runtime/doc/usr_05.txt @@ -10,7 +10,7 @@ make Vim start with options set to different values. Add plugins to extend Vim's capabilities. Or define your own macros. |05.1| The vimrc file -|05.2| The example vimrc file explained +|05.2| Example vimrc contents |05.3| Simple mappings |05.4| Adding a package |05.5| Adding a plugin @@ -27,10 +27,10 @@ Table of contents: |usr_toc.txt| You probably got tired of typing commands that you use very often. To start Vim with all your favorite option settings and mappings, you write them in -what is called the init.vim file. Vim executes the commands in this file when +what is called the init.vim file. Vim executes the commands in this file when it starts up. -If you already have a init.vim file (e.g., when your sysadmin has one setup +If you already have a init.vim file (e.g., when your sysadmin has one setup for you), you can edit it this way: > :edit $MYVIMRC @@ -56,80 +56,32 @@ This chapter only explains the most basic items. For more information on how to write a Vim script file: |usr_41.txt|. ============================================================================== -*05.2* The example vimrc file explained *vimrc_example.vim* +*05.2* Example vimrc contents *vimrc_example.vim* In the first chapter was explained how to create a vimrc file. > :exe 'edit' stdpath('config').'/init.vim' -In this section we will explain the various commands used in this file. This -will give you hints about how to set up your own preferences. Not everything -will be explained though. Use the ":help" command to find out more. - -> - set backspace=indent,eol,start - -This specifies where in Insert mode the <BS> is allowed to delete the -character in front of the cursor. The three items, separated by commas, tell -Vim to delete the white space at the start of the line, a line break and the -character before where Insert mode started. -> - - set autoindent - -This makes Vim use the indent of the previous line for a newly created line. -Thus there is the same amount of white space before the new line. For example -when pressing <Enter> in Insert mode, and when using the "o" command to open a -new line. +In this section we will explain the various commands that can be specified in +this file. This will give you hints about how to set up your own preferences. +Not everything will be explained though. Use the ":help" command to find out +more. > - set backup This tells Vim to keep a backup copy of a file when overwriting it. The backup file will have the same name as the original file with "~" added. See |07.4| > - set history=50 - +< Keep 50 commands and 50 search patterns in the history. Use another number if you want to remember fewer or more lines. > - - set ruler - -Always display the current cursor position in the lower right corner of the -Vim window. - -> - set showcmd - -Display an incomplete command in the lower right corner of the Vim window, -left of the ruler. For example, when you type "2f", Vim is waiting for you to -type the character to find and "2f" is displayed. When you press "w" next, -the "2fw" command is executed and the displayed "2f" is removed. -> - +-------------------------------------------------+ - |text in the Vim window | - |~ | - |~ | - |-- VISUAL -- 2f 43,8 17% | - +-------------------------------------------------+ - ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ - 'showmode' 'showcmd' 'ruler' - -> - set incsearch -< -Display matches for a search pattern while you type. - -> map Q gq This defines a key mapping. More about that in the next section. This -defines the "Q" command to do formatting with the "gq" operator. This is how -it worked before Vim 5.0. Otherwise the "Q" command repeats the last recorded -register. - +defines the "Q" command to do formatting with the "gq" operator. Otherwise the +"Q" command repeats the last recorded register. > vnoremap _g y:exe "grep /" .. escape(@", '\\/') .. "/ *.c *.h"<CR> @@ -138,14 +90,8 @@ This is a complicated mapping. You can see that mappings can be used to do quite complicated things. Still, it is just a sequence of commands that are executed like you typed them. + *vimrc-filetype* > - set hlsearch - -This option tells Vim to highlight matches with the last used search pattern. -The "if" command is very useful to set options only when some condition is -met. More about that in |usr_41.txt|. - - *vimrc-filetype* > filetype plugin indent on This switches on three very clever mechanisms: @@ -172,15 +118,27 @@ This switches on three very clever mechanisms: *restore-cursor* *last-position-jump* > - autocmd BufRead * autocmd FileType <buffer> ++once - \ if &ft !~# 'commit\|rebase' && line("'\"") > 1 && line("'\"") <= line("$") | exe 'normal! g`"' | endif + augroup RestoreCursor + autocmd! + autocmd BufRead * autocmd FileType <buffer> ++once + \ let s:line = line("'\"") + \ | if s:line >= 1 && s:line <= line("$") && &filetype !~# 'commit' + \ && index(['xxd', 'gitrebase'], &filetype) == -1 + \ | execute "normal! g`\"" + \ | endif + augroup END Another autocommand. This time it is used after reading any file. The complicated stuff after it checks if the '" mark is defined, and jumps to it -if so. The backslash at the start of a line is used to continue the command -from the previous line. That avoids a line getting very long. -See |line-continuation|. This only works in a Vim script file, not when -typing commands at the command-line. +if so. It doesn't do that for a commit or rebase message, which are likely +a different one than last time, and when using xxd(1) to filter and edit +binary files, which transforms input files back and forth, causing them to +have dual nature, so to speak. See also |using-xxd|. + +The backslash at the start of a line is used to continue the command from the +previous line. That avoids a line getting very long. See |line-continuation|. +This only works in a Vim script file, not when typing commands at the +command line. > command DiffOrig vert new | set bt=nofile | r ++edit # | 0d_ | diffthis @@ -244,26 +202,21 @@ The ":map" command (with no arguments) lists your current mappings. At least the ones for Normal mode. More about mappings in section |40.1|. ============================================================================== -*05.4* Adding a package *add-package* *vimball-install* - -A package is a set of files that you can add to Vim. There are two kinds of -packages: optional and automatically loaded on startup. +*05.4* Adding a package *add-package* -The Vim distribution comes with a few packages that you can optionally use. -For example, the vimball plugin. This plugin supports creating and using -vimballs (self-installing Vim plugin archives). +You may use |:packadd| to enable packages on demand. This is useful for plugins +you want to enable only sometimes. To enable `example_package`, use the +following command: > + packadd example_package -To start using the vimball plugin, add one line to your vimrc file: > - packadd vimball - -That's all! You can also type the command to try it out. Now you can find -help about this plugin: > - :help vimball +That's all! Now you can find help about this plugin: > + :help example_package This works, because when `:packadd` loaded the plugin it also added the -package directory in 'runtimepath', so that the help file can be found. The -tags for vimball's help are already created. If you need to generate the help -tags for a package, see the `:helptags` command. +package directory in 'runtimepath', so that the help file can be found. + +A package is a set of files that you can add to Vim. There are two kinds of +packages: optional and automatically loaded on startup. You can find packages on the Internet in various places. It usually comes as an archive or as a repository. For an archive you can follow these steps: @@ -273,7 +226,7 @@ an archive or as a repository. For an archive you can follow these steps: package. 2. unpack the archive in that directory. This assumes the top directory in the archive is "start": > - cd ~/.local/share/nvim/site/pack/fancy + cd ~/.local/share/nvim/site/pack/fancy unzip /tmp/fancy.zip < If the archive layout is different make sure that you end up with a path like this: @@ -342,7 +295,7 @@ That's all! Now you can use the commands defined in this plugin. Instead of putting plugins directly into the plugin/ directory, you may better organize them by putting them into subdirectories under plugin/. -As an example, consider using "~/.local/share/nvim/site/plugin/perl/*.vim" for +As an example, consider using "~/.local/share/nvim/site/plugin/perl/*.vim" for all your Perl plugins. |