How to access any given vim plugin documentation?

Question

I am new to vim and I've been asking a bunch of questions on here, most of which has to do with plugins. What is the correct way to access the documentation for plugin? As an example, I am using the this:

https://github.com/gu-fan/simpleterm.vim

The documentation on Gihub mentions the usage of: g:simpleterm.pos = 'below' to control where the terminal will appear.

My guess is that I only need to change this argument 'below' to something that I prefer. 'Top' seems to work. But about the other directions? 'Left', 'Right', 'East', 'West' do not work.

There are no ways for me to figure out the correct syntax. In vim, I tried:

:h simpleterm

That brings me to the same documentation on github, i.e only mentions of possible usage but no syntax.

This also happens with plugins like vim-airline, some vim themes...etc. But those are popular and so I can find answers via stackexchange.

Bottom line is: where should I dig for a complete documentation with all the possible syntax usage for a given plugin?

Thanks for your help.

Answer 1

In general a good plugin will provide good and complete documentation using Vim's own help system, :help, but sometimes it is hard to figure out the right topic name.

How to find documentation topics?

Vim's documentation uses tags to provide quick navigation, e.g. :help :s. This makes for a little chicken and egg problem because you might not know the help author choose for tags. Here are some ways to discover help topics:

• Use tab completion (and wildcards!) e.g. :h buff<tab> to list out buffer related topics
• Use <c-d> to list out completions instead of using <tab>
• Use :helpgrep {pat} to search for some patter in the help files. Similar to :vimgrep/:grep and will populate the quickfix list
• :help has a table of contents as well as tags to plugin help files (may need to run :helptags in so form)

So what about simpleterm.vim's documentation?

Sadly simpleterm.vim doesn't document the options for this behavior. You literally have to crack open the plugin and see what it is doing to figure out what options are available. It is using below which is short for :belowright followed by :split. This means you probably have options of :vertical, :leftabove, :aboveleft, :rightbelow, :belowright, :topleft, and/or :botright.

" bottom, right, top, left with regard to all the windows
let g:simpleterm.pos = 'botright'
let g:simpleterm.pos = 'botright vertical'
let g:simpleterm.pos = 'topleft'
let g:simpleterm.pos = 'topleft vertical'

" below, right, above, left with regard to the current window
let g:simpleterm.pos = 'belowright'
let g:simpleterm.pos = 'belowright vertical'
let g:simpleterm.pos = 'aboveleft'
let g:simpleterm.pos = 'aboveleft vertical'

It would probably be useful to read :h :vertical and the next few command to get a feel for all the split window modifiers. Actually reading all of :h windows would be a good idea.