Mastering the Vim Help System

From hanging out in #vim on the Freenode IRC channel one thing I've noticed is that although the majority of people asking for support are more than willing to read the appropriate help topic, they are not familiar enough with the available tools to do so effectively. The Vim help system is surprisingly powerful, very well written, and very complete. This post is written to expose the Vim user to some of the less known tips about finding help within Vim.

The Basics

Given a command, or option, or any given topic that you'd like to find more information on, the best place to start looking for help is with the :help command. For example if you want to look up details on the expandtab option you would type :help expandtab to get to the appropriate section as shown below.

Navigation With Bookmarks

Throughout the help documentation, you will find many terms surrounded by | symbols like |these-ones|. These terms are references to bookmarks. If you put the cursor on one of these references and press <C-]>, you will jump to that reference's corresponding bookmark. Bookmarks in the documentation are surrounded by * characters like *these-ones*. You can jump from topic to topic as much as you like, and pressing <C-T> at any time will take you backwards one step.

In fact, you can try the <C-]> trick on any word in the help system to attempt a jump to a help section on that word. The explicit references are there to take you to a specific destination though.

Help Completion

Ensure that that wildmenu option is turned on (typing :set wildmenu will enable it) and you can have some nice help topic <Tab> completion. By typing :h (Note: :h is short for :help) followed by a partial word and a <Tab> you will be shown a list of help topics that begin with the given pattern. Pressing <Tab> repeatedly here will cycle through the option. Press <Enter> to select the topic you want. The following screenshot is the result of typing :h expa<Tab>.

Another useful tip when you only know a partial name is <C-D> (Ctrl-D) completion. By typing a partial name and pressing <C-D>, you will get a list of available topics containing that partial word. For example, the following picture is a result of typing :h cursor<C-D>.

Search Help Using Regular Expressions

For more complex searches, we can use the :helpgrep command. This command takes a regular expression as an argument and will return a list of all occurrences of a match found in the help documentation. For example, if you wanted to find all occurrences of the term double-click you would type :helpgrep double-click. The result of this command is shown below.

As you can see in the bottom of that screenshot, there were a total of 14 occurrences of this search term in the documentation. Each of these occurrences are displayed to you one at a time. To cycle to the next occurrence, use the :cn command. To cycle backwards, use the :cp command.

Keep Your Own Tips Section

This section doesn't cover more tools for searching the help documentation, but instead it suggests a way to take advantage of the help system itself to keep track of your own tips. This is a method I've been using for about a month now, and I've found it extremely helpful.

Start by creating a new text file in your ~/.vim/doc/ directory. Let's call it mytips.txt. Put the following line as the very first line of the new file.

*mytips.txt*  My own set of tips...

This is really the only line that matters as far as format goes. The rest of the file can be pretty much free form, but you will benefit by keeping it relatively organized. I keep mine divided up in sections, each section beginning with a bookmark like *mytips-movement*. With these bookmarks, I can jump to these sections immediately using the :h mytips-movement command just as I can jump anywhere else in the help system. In order to make your new file work as a help document, you need to run a command to generate a tags file for it like this: :helptags ~/.vim/d/oc

I have several autocommands in my ~/.vimrc to make this process a little more automated. If you'd like to use them, stick the following lines in your ~/.vimrc.

autocmd BufWrite mytips.txt             :helptags ~/.vim/doc/
autocmd BufRead  mytips.txt             set filetype=help
autocmd BufRead  mytips.txt             set noreadonly
autocmd BufRead  mytips.txt             set modifiable

nmap <leader>h :tabnew ~/.vim/doc/mytips.txt<CR>

The first one generates a new helptags file each time you write your tips file to disk. This keeps you from having to do it manually, and ensures your tips will always be current. The second sets the filetype to 'help' so that you get the appropriate syntax highlighting when you edit your file, and the following two undo a couple of unwanted options that setting the filetype enables automatically. Finally, <Leader>h is mapped to opening the new tips file in a new tab for editing (tabs are only in Vim7 or newer).

Now, when you discover a new tip, type <Leader>h (\h by default, see :he leader), add it to the file, and save it. Done!