Vim Tips Wiki
Register
(Rough merge in from 229)
(Change <tt> to <code>, perhaps also minor tweak.)
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
__NOTOC__
 
 
{{TipImported
 
{{TipImported
 
|id=882
 
|id=882
 
|previous=880
 
|previous=880
 
|next=883
 
|next=883
|created=February 21, 2005
+
|created=2005
 
|complexity=basic
 
|complexity=basic
 
|author=David S
 
|author=David S
|version=5.7
+
|version=6.0
 
|rating=33/25
 
|rating=33/25
|category1=Usage
+
|category1=Getting started
 
|category2=
 
|category2=
 
}}
 
}}
Vim's help is remarkably thorough, but it definitely takes some getting used to if you are new to it.
+
Vim's help is remarkably helpful, but in order to use it effectively you need to spend a few minutes learning how it is organised.
   
  +
==Getting started==
Starting out, remember:
 
  +
Try these examples:
*Get specific help by browsing with <tt><nowiki>:help</nowiki></tt> or by jumping to a topic with <tt><nowiki>:help <topic></nowiki></tt>
 
  +
*Enter <code>:help</code> to browse help. Scroll down the help page to see the quickref and tutor links, and the table of contents.
*After typing your help search, CTRL-D will list all matches to your subject so that you can narrow what you are looking for. For example, <tt><nowiki>:help scroll<C-D></nowiki></tt>. Use <tt><nowiki><TAB></nowiki></tt> to scroll.
 
  +
*Enter {{help|pattern}} for help on the topic ''pattern'' (for example).
*You can search through all the help files with the <tt>:helpgrep</tt> command.
 
  +
*<code>:h pattern</code> is the same (the <code>:help</code> command can be abbreviated).
*You can search within a single help file just like within a regular file using <tt>/</tt>.
 
*{{help|quickref}} is a good place to start.
 
*CTRL-] follows a link, and CTRL-T goes back.
 
*Read a new chapter from the main help (:help) file every now and again to learn something new!
 
   
  +
Command completion can be used when entering a help topic:
==References==
 
  +
*Type <code>:h patt</code> then press Ctrl-D to list all topics that contain "<code>patt</code>".
*{{help|help}}
 
  +
*Type <code>:h patt</code> then press Tab to scroll through the topics that start with "<code>patt</code>".
*{{help|help-context}}
 
  +
*If you have set the <code>{{help|'wildmenu'|prefix=no}}</code> option (e.g. by using <code>:set wildmenu</code>), then <code>:h patt</code> followed by <code><Tab></code> opens a menu on the statusline, with all help topics containing "<code>patt</code>". You can select any item in the menu with the arrow keys or more presses of the <code><Tab></code> key to fill in the rest of your command line.
*{{help|:helpgrep}}
 
   
  +
Links:
==See also==
 
  +
*Enter <code>:h</code> to open the main help page.
*Remember to search this wiki (see 'search' in the sidebar)!
 
  +
*Type <code>/quick</code> to search for "quick" (should find the <code>quickref</code> link).
*Search the [[Vim documentation|FAQ and other guides on our documentation page]]
 
  +
*Press Ctrl-] to follow the link (jump to the quickref topic).
*Search the [http://www.vim.org/maillist.php archives of the Vim mailing lists]
 
  +
*After browsing the quickref topic, press Ctrl-T to go back to the previous topic.
  +
*You can also press Ctrl-O to jump to older locations, or Ctrl-I to jump to newer locations.
   
  +
Searching:
==Vim built-in help==
 
  +
*Search within a help file using <code>/</code> like you would when searching any file.
{{Todo}}
 
 
*Search all the help files with the <code>:helpgrep</code> command, for example:
*'''Merge in following info from deleted tip 229'''
 
  +
::<code>:helpgrep \csearch.\{,12}file</code>
  +
::<code>\c</code> means the pattern is case insensitive.
  +
::The pattern finds "search" then up to 12 characters followed by "file".
  +
:You will then see the first match. To see other matches for the same pattern, use:
  +
::<code>:cnext</code>
  +
::<code>:cprev</code>
  +
::<code>:cnfile</code>
  +
::<code>:cpfile</code>
  +
::<code>:cfirst</code>
  +
::<code>:clast</code>
  +
:and even
  +
::<code>:cc</code>
  +
:which brings you back to the current match after you scrolled the helpfile, or
  +
::<code>:copen</code>
  +
:which will list out all the matches in a separate window. Read up on these commands with the <code>:help</code> entry for each of them!
   
  +
Each week (or more often if you prefer), read a new section from the <code>:help</code> page to learn something new!
Vim built-in help is the fastest way to get info, once you know what to look for. You can try this command to show a list of related topics:
 
<pre>
 
:h &lt;topic&gt;&lt;c-d&gt;
 
</pre>
 
   
  +
==Context==
It is "some topic" followed by the key sequence Ctrl-D. For eg:
 
  +
Each help topic has a context:
<pre>
 
  +
{| class="cleartable"
:h xterm&lt;c-d&gt;
 
  +
! style="width:4em" | Prefix !! style="width:8em" | Example !! Context
</pre>
 
  +
|-
will show all the help topics matching xterm. Then you can do completion/copy-n-paste the topic you are searching. Of course you can cycle through all the topics through repeated &lt;TABS&gt;, but if the number of hits are huge, it is cumbersome.
 
  +
|<code>:</code> || <code>:h :r</code> || ex command (command starting with a colon)
  +
|-
  +
|''none'' || <code>:h r</code> || normal mode
  +
|-
  +
|<code>v_</code> || <code>:h v_r</code> || visual mode
  +
|-
  +
|<code>i_</code> || <code>:h i_CTRL-W</code> || insert mode
  +
|-
  +
|<code>c_</code> || <code>:h c_CTRL-R</code> || ex command line
  +
|-
  +
|<code>/</code> || <code>:h /\r</code> || search pattern (in this case, <code>:h \r</code> also works)
  +
|-
  +
|<code>'</code> || <code>:h 'ro'</code> || option
  +
|-
  +
|<code>-</code> || <code>:h -r</code> || Vim argument (starting Vim)
  +
|}
  +
  +
Sometimes you want to know what a particular control key means to Vim. For example, to see all help topics containing "ctrl-r", type <code>:h&nbsp;ctrl-r</code> then press Ctrl-D. The following examples show the help for pressing various keys in different contexts.
  +
{| class="cleartable"
  +
! style="width:8em" | Example !! Help for key
  +
|-
  +
|<code>:h CTRL-R</code> || Ctrl-R in normal mode
  +
|-
  +
|<code>:h i_CTRL-R</code> || Ctrl-R in insert mode
  +
|-
  +
|<code>:h c_CTRL-R</code> || Ctrl-R in command mode
  +
|-
  +
|<code>:h v_CTRL-V</code> || Ctrl-V in visual mode
  +
|}
  +
  +
==Simplify help navigation==
  +
The following mappings simplify navigation when viewing help:
  +
*Press Enter to jump to the subject (topic) under the cursor.
  +
*Press Backspace to return from the last jump.
  +
*Press <code>s</code> to find the next subject, or <code>S</code> to find the previous subject.
  +
*Press <code>o</code> to find the next option, or <code>O</code> to find the previous option.
   
  +
Create file <code>~/.vim/ftplugin/help.vim</code> (Unix) or <code>$HOME/vimfiles/ftplugin/help.vim</code> (Windows) containing:
You can also use this command:
 
 
<pre>
 
<pre>
  +
nnoremap <buffer> <CR> <C-]>
:helpgrep {pattern}
 
  +
nnoremap <buffer> <BS> <C-T>
  +
nnoremap <buffer> o /'\l\{2,\}'<CR>
  +
nnoremap <buffer> O ?'\l\{2,\}'<CR>
  +
nnoremap <buffer> s /\|\zs\S\+\ze\|<CR>
  +
nnoremap <buffer> S ?\|\zs\S\+\ze\|<CR>
 
</pre>
 
</pre>
  +
The following mappings (which can go in your vimrc) simplify navigating the results of {{help|quickfix|prefix=no}} commands such as (among others) <code>:helpgrep</code>
to search all the help files for a pattern.
 
 
BTW, &lt;c-d&gt; can be used for listing other matches also.
 
For example:
 
 
<pre>
 
<pre>
  +
:nnoremap <S-F1> :cc<CR>
:e &lt;c-d&gt; "to show list of files matching the pattern
 
  +
:nnoremap <F2> :cnext<CR>
:buf &lt;c-d&gt; "to show list of open buffers etc.
 
  +
:nnoremap <S-F2> :cprev<CR>
  +
:nnoremap <F3> :cnfile<CR>
  +
:nnoremap <S-F3> :cpfile<CR>
  +
:nnoremap <F4> :cfirst<CR>
  +
:nnoremap <S-F4> :clast<CR>
 
</pre>
 
</pre>
  +
 
==References==
 
*{{help|id=help.txt|label=''}}
 
*{{help|:help}}
 
*{{help|:helpgrep}}
  +
*{{help|helphelp.txt}}
  +
*{{help|quickref.txt}}
  +
 
==See also==
 
*Remember to search this wiki (see 'search' in the sidebar)!
 
*Search the [[Vim documentation|FAQ and other guides on our documentation page]]
 
*Search the [http://www.vim.org/maillist.php archives of the Vim mailing lists]
   
 
==Comments==
 
==Comments==
Line 69: Line 134:
 
What it does:
 
What it does:
 
*First tab: longest match, list in the statusbar.
 
*First tab: longest match, list in the statusbar.
*Next tabs: cycle through matches. (Like in the shell)
+
*Following tabs: cycle through matches.
 
----
 

Revision as of 07:53, 11 July 2012

Tip 882 Printable Monobook Previous Next

created 2005 · complexity basic · author David S · version 6.0


Vim's help is remarkably helpful, but in order to use it effectively you need to spend a few minutes learning how it is organised.

Getting started

Try these examples:

  • Enter :help to browse help. Scroll down the help page to see the quickref and tutor links, and the table of contents.
  • Enter :help pattern for help on the topic pattern (for example).
  • :h pattern is the same (the :help command can be abbreviated).

Command completion can be used when entering a help topic:

  • Type :h patt then press Ctrl-D to list all topics that contain "patt".
  • Type :h patt then press Tab to scroll through the topics that start with "patt".
  • If you have set the 'wildmenu' option (e.g. by using :set wildmenu), then :h patt followed by <Tab> opens a menu on the statusline, with all help topics containing "patt". You can select any item in the menu with the arrow keys or more presses of the <Tab> key to fill in the rest of your command line.

Links:

  • Enter :h to open the main help page.
  • Type /quick to search for "quick" (should find the quickref link).
  • Press Ctrl-] to follow the link (jump to the quickref topic).
  • After browsing the quickref topic, press Ctrl-T to go back to the previous topic.
  • You can also press Ctrl-O to jump to older locations, or Ctrl-I to jump to newer locations.

Searching:

  • Search within a help file using / like you would when searching any file.
  • Search all the help files with the :helpgrep command, for example:
:helpgrep \csearch.\{,12}file
\c means the pattern is case insensitive.
The pattern finds "search" then up to 12 characters followed by "file".
You will then see the first match. To see other matches for the same pattern, use:
:cnext
:cprev
:cnfile
:cpfile
:cfirst
:clast
and even
:cc
which brings you back to the current match after you scrolled the helpfile, or
:copen
which will list out all the matches in a separate window. Read up on these commands with the :help entry for each of them!

Each week (or more often if you prefer), read a new section from the :help page to learn something new!

Context

Each help topic has a context:

Prefix Example Context
: :h :r ex command (command starting with a colon)
none :h r normal mode
v_ :h v_r visual mode
i_ :h i_CTRL-W insert mode
c_ :h c_CTRL-R ex command line
/ :h /\r search pattern (in this case, :h \r also works)
' :h 'ro' option
- :h -r Vim argument (starting Vim)

Sometimes you want to know what a particular control key means to Vim. For example, to see all help topics containing "ctrl-r", type :h ctrl-r then press Ctrl-D. The following examples show the help for pressing various keys in different contexts.

Example Help for key
:h CTRL-R Ctrl-R in normal mode
:h i_CTRL-R Ctrl-R in insert mode
:h c_CTRL-R Ctrl-R in command mode
:h v_CTRL-V Ctrl-V in visual mode

Simplify help navigation

The following mappings simplify navigation when viewing help:

  • Press Enter to jump to the subject (topic) under the cursor.
  • Press Backspace to return from the last jump.
  • Press s to find the next subject, or S to find the previous subject.
  • Press o to find the next option, or O to find the previous option.

Create file ~/.vim/ftplugin/help.vim (Unix) or $HOME/vimfiles/ftplugin/help.vim (Windows) containing:

nnoremap <buffer> <CR> <C-]>
nnoremap <buffer> <BS> <C-T>
nnoremap <buffer> o /'\l\{2,\}'<CR>
nnoremap <buffer> O ?'\l\{2,\}'<CR>
nnoremap <buffer> s /\|\zs\S\+\ze\|<CR>
nnoremap <buffer> S ?\|\zs\S\+\ze\|<CR>

The following mappings (which can go in your vimrc) simplify navigating the results of quickfix commands such as (among others) :helpgrep

:nnoremap <S-F1>  :cc<CR>
:nnoremap <F2>    :cnext<CR>
:nnoremap <S-F2>  :cprev<CR>
:nnoremap <F3>    :cnfile<CR>
:nnoremap <S-F3>  :cpfile<CR>
:nnoremap <F4>    :cfirst<CR>
:nnoremap <S-F4>  :clast<CR>

References

See also

Comments

Also see the wildmenu. My settings:

set wildmenu wildmode=longest:full,full

What it does:

  • First tab: longest match, list in the statusbar.
  • Following tabs: cycle through matches.