puterakahfi / zeavim.vim

Zeal for Vim

Zeavim, Zeal for Vim

Description | Installation | Usage | Mapping | Commands | Customization | Notes

Description

Zeavim allows to use the offline documentation browser Zeal from Vim.

Features

• Search for word under cursor, a motion or a visual selection.
• Search without losing focus from Vim if Zeal is already opened (Need wmctrl on UNIX).
• Possibility to specify dynamically a docset.
• Narrow search with a query.
• Allows using multiple docsets.
• Docset name completion.
• Define you own docsets using file types, extentions or regex.
• Supports docsets specific to file names (e.g gulpfile.js)
• Works on GNU/Linux and Windows.

Starting from version 2.0.0 the plugin is following semantic versionning 2.0.0.

Installation

To use zeavim, you need of course to have Zeal installed. Grab it from here and install it .

Manual installation

Install the distributed files into Vim runtime directory which is usually ~/.vim/, or $HOME/vimfiles on Windows.

Using a plugin manager

And this is the best way, use a vim plugin manager:

Plugin manager	In vimrc	Installation command
Vim-plug	Plug 'KabbAmine/zeavim.vim'	PlugInstall
Vundle	Plugin 'KabbAmine/zeavim.vim'	PluginInstall
NeoBundle	NeoBundle 'KabbAmine/zeavim.vim'	NeoBundleInstall

Usage

There are 3 ways of using zeavim:

1. <leader>z

   Search for word under cursor with the docset defined automatically⁺.

2. gz{motion}

   Search for a motion with the docset defined automatically⁺.

3. <leader><leader>z

   Narrow search with a docset⁺ and a query (A default docset is provided).

   

   • Multiple docsets can be defined, just separate them by a comma.
   • The docset name can be completed using tab, see completion for that.

Mapping

You can easily change the mapping keys of zeavim:

nmap gzz <Plug>Zeavim           " <leader>z (NORMAL mode)
vmap gzz <Plug>ZVVisSelection   " <leader>z (VISUAL mode)
nmap gz <Plug>ZVMotion         " gz{motion} (NORMAL mode)
nmap gZ <Plug>ZVKeyDocset      " <leader><leader>z

You can disable the default mappings, but this is useful only if you're not going to use all the <Plug>'s above.

Commands

Main commands

For those of you who prefer commands, here they are:

Zeavim    " NORMAL mode
ZvV       " VISUAL mode
ZvKD      " Type docset and query

Specify manually a docset

If you need a lazy way to specify a docset, you can use:

Docset DOCSET_NAME

As an example, I'm working on a scss file but I want to get compass documentation when using Zeavim, so I just need to specify manually this docset:

Docset compass

Then Zeavim only for the current buffer will use compass as a docset. Note that you can define multiple docsets here.

The docset name can be completed, for that see completion.

To revert that and get zeavim working like usually, a simple Docset without argument is enough.

Customization

Location of Zeal

By default zeavim looks for an executable named zeal on your PATH for UNIX and in %ProgramFiles%/Zeal/zeal.exe for Windows. You can specify Zeal's location manually by adding in your vimrc:

let g:zv_zeal_executable = 'path/to/zeal'

Or if you're using both OS:

let g:zv_zeal_executable = has('win32') ?
			\ 'path/to/zeal.exe' :
			\ 'path/to/zeal'

Add file types +

To define the docset, the plugin uses by order one of those:

• The value defined by :Docset command.
• The file name.
• The file extension.
• The file type.

If you need to add another file names, extensions or file types (Or overwrite those by default), you can use g:zv_file_types variable.

It's a dictionary where keys can be filename, file extension or file type and values are the docset names.

" For the docset, not mandatory but you can use underscores instead of spaces
let g:zv_file_types = {
    \ 'FILE_NAME' : 'DOCSET_NAME',
    \ 'EXTENSION' : 'DOCSET NAME',
    \ 'FILE_TYPE' : 'DOCSET_NAME',
    \ }

Here again you can define multiple docsets for a type, just separate them by a comma.

'TYPE': 'DOCSET1,DOCSET2'

If a key starts with ^, it will be considered as a regex. It is useful if you want to define many types to one docset (Note that the regex will use vim magic).

e.g

let g:zv_file_types = {
			\ 'cpp'                   : 'c++',
			\ '^(G|g)runtfile\.'      : 'grunt',
			\ '^(G|g)ulpfile\.'       : 'gulp',
			\ '.htaccess'             : 'apache_http_server',
			\ '^(md|mdown|mkd|mkdn)$' : 'markdown',
			\ 'css'                   : 'css,foundation,bootstrap_4',
		\ }

N.B: All the values above are already defined in the plugin, a part the css one.

Disable default mappings

You can disable the default mappings:

let g:zv_disable_mapping = 1

If you're using all the functionalities of the plugin (NORMAL, VISUAL, docset and query manual input), no need of setting this variable, just map the <Plug>'s normally.

Docset name completion

When using <leader><leader>z or the command Docset, you can get a docset name completion with Tab. The docset names are taken from your zeal's docset directory (The one specified in Zeal's options).

By default zeavim assumes that Zeal docsets are located in %LOCALAPPDATA%\Local\Zeal\Zeal\docsets, which expands into something like C:\Users\you\AppData\Local\Zeal\Zeal\docsets for Windows and ~/.local/share/Zeal/Zeal/docsets for UNIX systems.

If you have them in a different folder, just set the correct path in g:zv_docsets_dir variable.

e.g

let g:zv_docsets_dir = has('win32') ?
			\ 'path/to/docsets/in/win' :
			\ 'path/to/docsets/in/unix'

---

THE NEXT OPTION WILL BE REMOVED, SO DON'T RELAY ON IT

Another way to enable completion just for a few docsets (Why not!), instead of g:zv_docsets_dir use g:zv_lazy_docset_list.

e.g

let g:zv_lazy_docset_list = [ 'Compass', 'Bootstrap', 'Vagrant', 'Font Awesome' ]

My configuration

nmap gzz <Plug>Zeavim
vmap gzz <Plug>ZVVisSelection
nmap gz <Plug>ZVMotion
nmap gZ <Plug>ZVKeyDocset
let g:zv_file_types = {
			\ 'python': 'python 3',
			\ 'ruby': 'ruby,ruby 2'
		\ }
let g:zv_docsets_dir = has('unix') ?
			\ '~/Important!/docsets_Zeal/' :
			\ 'Z:/myUser/Important!/docsets_Zeal/'

Notes

Zeavim was my first vim plugin and it was created in the beginning for a personal use, so please feel free to report issues and submit PR. I usually answer in 1-2 days.

Thanks to Jerzy Kozera for creating such wonderful open-source application.

Thanks to Bram Moolenaar for creating the best piece of software in the world ❤️

Thanks to you if you're using zeavim.