3 min read

On Viewing Documentation in Vim

I just discovered something delightful. I’m giddy and extremely titillated. I can access both the man pages and the docs for a particular language that matches that of the file type for the word underneath the cursor.

Holy zap!

Now, that was a mouthful, how about an example. Yes!

By default, Vim allows for opening the man page (if there is one) of the keyword underneath the cursor by pressing Shift + k.

K			Run a program to lookup the keyword under the
			cursor.  The name of the program is given with the
			'keywordprg' (kp) option (default is "man").

Ok, that’s great, especially when coding in C or doing any kind of shell scripting! But wait! There’s more.

Imagine that you’re programming in Go, and you can access not only the man pages but also Go docs. What?!? Yes!

How does Vim determine which program to run? As the snippet from the docs above tells us, the keywordprg (or its shortened version kp) option is responsible for that.

To see this in action, open any file in Vim and run the command :set kp. Vim will tell you what it has set the option’s value to be for that particular file.

For example, when I open a Python script, the result of running :set kp is keywordprg=pydoc.


Whoa, is that for real? Yes! A thousand times, Yes!

Just For Fun

  1. How can I invoke Vim and not have it parse my .vimrc?

    Vim reads the .vimrc run command file every time it’s loaded, and so it loads all of the plugins and customizations, if any. I have quite a bit.

    That’s only a :help -u away (in a Vim session)!

    Inspecting the documentation for -u within the vim-arguments section, the following passage looks like a winner:

     When {vimrc} is equal to "NONE" (all uppercase), all initializations from files
     and environment variables are skipped, including reading the gvimrc file when the
     GUI starts.  Loading plugins is also skipped.
    $ vim -u NONE server.c
  2. How can I see all of the defined mappings?

     n  ,K            :call <SNR>15_PreGetPage(0)<CR>

    So, after seeing this, I knew that I was wrong about my assumption. It’s a plugin, but not one loaded by vim-plug. Instead, it’s the native ftplugin/man.vim that’s the bad guy and is referenced in my .vim.mappings file, sourced by .vimrc:

     runtime ftplugin/man.vim

    How did I know that from the cryptic output above? Well, I didn’t. I just knew of the native ftplugin/man.vim plugin and the function above looked familiar. Just dumb luck, really.

    Ah, let’s now look at the help section for man, :help man. And there it is, the answer we’ve been seeking:

     To start using the :Man command before any manual page has been loaded,
     source this script from your startup vimrc file:
             runtime ftplugin/man.vim
     Global mapping:
     <Leader>K	Displays the manual page for the word under the cursor.
     <Plug>ManPreGetPage  idem, allows for using a mapping: >
                 nmap <F1> <Plug>ManPreGetPage<CR>