Vim: Powerful “Shift + K”

Most Vim users know the shortcut Shift + K, this article is to tell a bit more than what they know.

Photo by Syed Ali on Unsplash

Brief Introduction

When you open Vim and start to program or reading code, you can type Shift + K when you have cursor on some word. For example, when you see below code in one Python script file:

You might not know what’s argparse and how to use it. Then, you can type Shift + K to show Python document about it without exit Vim. (P.S. By using the plugin somini/pydoc.vim, we can open the Python help document in new buffer.)

Figure 1 — Help Document on Python Module ‘argparse’

So, that means Shift + K can be used not only for Vim help document, but also for any available help document in system for current file type.

Another example, when you program Bash script and want to check document about the command grep, then you don’t need to switch to another terminal window to type man grep, instead, you just need to type Shift + K in Vim when you have cursor under the word grep, which is very convenient.

After reading help document, you can type q for twice or q + Enter to go back to Vim editor.

Finally, for sure, when you go through Vim help document (:help to open Vim help document), you can use Shift + K to jump to any position for those parts you don’t understand or aren’t familiarized yet, as long as the word under the cursor has relevant help document. If there is no help document for the word under the cursor, you will get error message like: “E149: Sorry, no help for around:”. Maybe you already noticed that the word might include punctuation like “around:” in the error message. How to avoid that punctuation is also treated as part of the word? I haven’t go the answer yet. If there is no ‘:’ after “around”, Shift + K will bring you to the help section “{move-around}”. (P.S. By setting the option iskeyword or isk , we can let the word under cursor exclude the invalid characters for keyword. For example, set isk=a-z,A-Z,48-57,_,.,-,> would be helpful.)

Dive Deeper

Now, we can ask a few questions: How does it work in background? Any magic there? And how to solve the problem when I encounter “No manual entry for ***”? Is it possible to load any help document on-demand? For example, I want to show Javadoc of some Java classes which I am not very familiarized. What shall do?

To answer the questions about background working mechanism, we need to check Vim help document about Shift + K — type :help K in Vim (it took me quite a few minutes to know about that).

As you see, it’s used to “Run a program to lookup the keyword under the cursor.” And there is one option keywordprg to control what program to run for Shift + K . Default program is man and if keywordprg is empty, then :help will be used. You can see value of keywordprg in your Vim by command :set keywordprg or :se keywordprg. In my Vim, it returns keywordprg=:help when I run :se keywordprg during reading Vim help document. So, is the value of the option keywordprg static? If it is, then why I can get help document of Python module argparse when I use Shift + K for under-cursor-word argparse in Python script? You know, if I directly type :help argparse I can see nothing but an error message “E149: Sorry, no help for argparse”. That must be some more thing need to know.

In fact, when I open Python script and then run command :se keywordprg or :se kp it returns keywordprg=pydoc ! (I was just excited when I saw that first time, because I finally feel more clear about this magic thing.) Obviously, this option can be combined with filetype. To verify it, I did the same when I open one Bash script. As expected, it’s keywordprg=man !

To know about keywordprg , I opened Vim help document about it by Shift + K under keywordprg . The help document tells some rules about it.

As I get to know this option is connected to filetype, and filetype should be configured globally in Vim environment. When I run :se I got all options including runtimepath where I can check how the option keywordprg is configured. By running the command grep -riIEHn keywordprg /usr/share/vim | grep pydoc I got the answer:

 > grep -riIEHn keywordprg /usr/share/vim/ | grep pydoc
/usr/share/vim/vim82/ftplugin/python.vim:122:" Use pydoc for keywordprg.
/usr/share/vim/vim82/ftplugin/python.vim:128: setlocal keywordprg=python3\ -m\ pydoc
/usr/share/vim/vim82/ftplugin/python.vim:130: setlocal keywordprg=python\ -m\ pydoc

And by checking the filetype plugin file for Java, I get to know there is no configuration for the option keywordprg , so it will be default value man . Thus, in Java source code, when you type Shift + K under for String , it will bring you to “Linux Programmer’s Manual” for STRING.

Therefore, if we want to see Java API document in VIM by Shift + K , we need to setup plain text document library for Java API and maybe possible to register it into mandb. Then, we can use default Shift + K to read Java help documentation in Vim. In theory, it’s doable (e.g. by help2man?). But maybe it’s not very necessary, as we can live with Browser and we don’t need to do everything within Vim. In fact, we can read(or jump to) Java source code file in Vim by decompressing the to somewhere and setup ctags for it. Then, we can add below line to remap K to tag command to jump to the target file which has tag for the keyword under cursor:

:au FileType java :nnoremap K :tag <C-R><C-W><CR>

And by below line, we can avoid using the full qualified class name or package name as keyword — by removing dot(.) from keyword:

:au FileType java :set isk=a-z,A-Z,48-57,_

In that way, it becomes very comfortable to read java source code files, even for big project.

Later, I created one function for above 2 lines:

53 function! s:set_k()
54 :setlocal isk=a-z,A-Z,48-57,_
55 :nnoremap <buffer> K :tag <C-R><C-W><CR>
56 endfunction

And call the function for file types java and scala:

50 :autocmd FileType java call s:set_k()
51 :autocmd FileType scala call s:set_k()

Maybe you noticed the changes in the function compare to previous statements:

  • set is changed to setlocal: because we want to make change only for function caller rather than globally.
  • <buffer> is added after :nnoremap for the same reason with setlocal.

Without those 2 changes, it might result in the chaos — K becomes always to find tags rather than use keywordprg for even other files types than java or scala.

At last, maybe you already know, but I want to say it again: you can set the option keywordprg as you want (even you don’t need it in normal case). For example,

:setlocal kp=man

Wish you are happy with this article and get to know how to use the powerful Vim shortcut Shift + K, how does it work and how to configure it.

Thanks for your reading! And happy coding!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store