Vim Tips Wiki
Don't have an account?
Register
Register
in: VimTip, Getting started

Changes: Learn to use help

Back to page
Edit
(→‎References: :help references in index.txt still broken)
mNo edit summary
Tag: sourceedit
(16 intermediate revisions by 6 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=Getting started
  
|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>:help</tt> or by jumping to a topic with <tt>:help <topic></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>:help scroll<C-D></tt>. Use <tt><Tab></tt> to scroll.
  
  +
*Enter {{help|pattern}} for help on the topic ''pattern'' (for example).
−
*Each help topic has a context. For example, topics about "ex" commands all start with :, topics about insert-mode commands all start with i_, and topics about options all are surrounded by single-quotes (i.e., "'''<tt>'</tt>'''").
  
−
*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}} (working link [http://vimdoc.sourceforge.net/htmldoc/index.html#help-context here])
  
  +
*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 tips 179, 229, 326'''
  
  +
::<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 <topic><c-d>
  
−
</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<c-d>
  
  +
! 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 <TABS>, 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.
−
You can also use this command:
  
  +
{| class="cleartable"
−
<pre>
  
  +
! style="width:8em" | Example !! Help for key
−
:helpgrep {pattern}
  
  +
|-
−
</pre>
  
  ⚫
|<code>:h CTRL-R</code> || Ctrl-R in normal mode
−
to search all the help files for a pattern.
  
  +
|-
  ⚫
|<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:
−
BTW, <c-d> can be used for listing other matches also.
  
−
For example:
  
 
<pre>
  
<pre>
  ⚫
nnoremap <buffer> <CR> <C-]>
−
:e <c-d> "to show list of files matching the pattern
  
  ⚫
nnoremap <buffer> <BS> <C-T>
−
:buf <c-d> "to show list of open buffers etc.
  
  ⚫
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>
−  
−
See {{help|quickref}} for a Vim Command Quick Reference Page &ndash; brilliant for beginners and oldtimers alike.
  
−  
−
===Other Help Tips===
  
 
<pre>
  
<pre>
  +
:nnoremap <S-F1> :cc<CR>
−
:h visual<C-D><Tab> : obtain list of all visual help topics
  
  +
:nnoremap <F2> :cnext<CR>
−
: Press Tab to step through them.
  
  +
:nnoremap <S-F2> :cprev<CR>
−
:h CTRL<C-D> : list help of all control keys
  
  +
:nnoremap <F3> :cnfile<CR>
−
:h :r : help for :ex command
  
  +
:nnoremap <S-F3> :cpfile<CR>
⚫
:h CTRL-R : normal mode
  
  +
:nnoremap <F4> :cfirst<CR>
−
:h \r : what's \r in a regexp
  
  +
:nnoremap <S-F4> :clast<CR>
⚫
:h i_CTRL-R : help for say <C-R> in insert mode
  
⚫
:h c_CTRL-R : help for say <C-R> in command mode
  
⚫
:h v_CTRL-V : visual mode
  
−
:h tutor : Vim Tutor
  
−
gvim -h : command line
  
 
</pre>
  
</pre>
   
  ⚫
==References==
⚫
==Simplify help navigation==
  
  +
*{{help|id=help.txt|label=''}}
−
Vim help has hyperlink support - you can press <C-]> over |some subject| or 'some option' to read more about particular term. Return with Ctrl-T.
  
  ⚫
*{{help|:help}}
  ⚫
*{{help|:helpgrep}}
  +
*{{help|helphelp.txt}}
  +
*{{help|quickref.txt}}
   
  ⚫
==See also==
⚫
The following mappings simplify help buffer navigation:
  
  ⚫
*Remember to search this wiki (see 'search' in the sidebar)!
−
*pressing s(or S) will find next(previous) subject from cursor position
  
  ⚫
*Search the [[Vim documentation|FAQ and other guides on our documentation page]]
−
*pressing o(or O) will find next(previous) option from cursor position
  
  ⚫
*Search the [http://www.vim.org/maillist.php archives of the Vim mailing lists]
⚫
*pressing Enter will jump to subject under cursor
  
⚫
*pressing Backspace will return from the last jump
  
−  
−
Put them into help filetype plugin (like ~/.vim/ftplugin/help.vim on Unix).
  
−  
−
<pre>
  
⚫
nmap <buffer> <CR> <C-]>
  
⚫
nmap <buffer> <BS> <C-T>
  
⚫
nmap <buffer> o /'[a-z]\{2,\}'<CR>
  
⚫
nmap <buffer> O ?'[a-z]\{2,\}'<CR>
  
⚫
nmap <buffer> s /\|\S\+\|<CR>
  
⚫
nmap <buffer> S ?\|\S\+\|<CR>
  
−
</pre>
  
   
 
==Comments==
  
==Comments==
Line 107: 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.
−  
−
----
  
−  
−
In addition to C-] and C-T, C-O and C-I can be used to jump backward and forward in the jump list history.
  

Revision as of 22:25, 17 April 2016

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.
Community content is available under CC-BY-SA unless otherwise noted.