Zeavim, Zeal for Vim

Description | Installation | Usage | Mapping | Commands | Settings | Notes

Description

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

Features

• Search for word under cursor, visual selection or the result of a motion/text-object.
• Search without losing focus in GNU/Linux.
• Narrow search with a docset or a query.
• Allow using multiple docsets.
• Docset names completion.
• Define you own docsets using patterns.
• Work on GNU/Linux and Windows.

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

With Vim-plug:

Plug 'KabbAmine/zeavim.vim'

Usage

There are 3 ways of using zeavim:

1. <leader>z or :Zeavim\ZeavimV

   Search for the word under cursor or the current visual selection with the docset defined automatically⁺.

2. gz{motion/text-object}

   Act like an operator and search for the result of a motion/text-object with the docset defined automatically⁺ (e.g. gziW will search for the inner Word).

3. <leader><leader>z or :Zeavim!

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

   

   • Multiple docsets can be defined, just separate them by a comma.
   • Docset name(s) can be completed using tab.

⁺ The current file type by default.

Mapping

Use the following to change the mappings:

nmap <leader>z <Plug>Zeavim
vmap <leader>z <Plug>ZVVisSelection
nmap gz <Plug>ZVOperator
nmap <leader><leader>z <Plug>ZVKeyDocset

N.B: The old <Plug>ZVMotion is still available to maintain compatibility.

Commands

Main commands

:Zeavim     " NORMAL mode (The same as <Plug>Zeavim)
:ZeavimV    " VISUAL mode (The same as <Plug>ZVVisSelection)
:Zeavim!    " Ask for docset and query (The same as <Plug>ZVKeyDocset)

N.B: The commands ZvV and ZVKeyDocset are still available to maintain compatibility with older versions of the plugin.

Specify manually a docset

:Docset DOCSET1,DOCSET2

If you need a lazy way to specify a docset(s), you can use the command above.
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.
To set back the initial docset, a simple Docset without argument is enough.

• Note that you can define multiple docsets here, separated by comma(s).
• The docset name(s) can be completed.

Settings

Please refer to the doc file for a full description of the options.

• g:zv_zeal_executable - Define location of zeal's executable.

  default:

  let g:zv_zeal_executable = has('win32')
              \ ? $ProgramFiles . '\Zeal\zeal.exe'
              \ : 'zeal'
  

• g:zv_file_type - Map specific regex patterns (file names, file types or file extensions) to docset(s).

  default:

  let g:zv_file_types = {
              \   'scss': 'sass',
              \   'sh'  : 'bash',
              \   'tex' : 'latex'
              \ }
  

  e.g:

  let g:zv_file_types = {
                  \    'css'                      : 'css,foundation',
                  \    '.htaccess'                : 'apache_http_server',
                  \    '\v^(G|g)runt\.'           : 'gulp,javascript,nodejs',
                  \    '\v^(G|g)ulpfile\.'        : 'grunt',
                  \    '\v^(md|mdown|mkd|mkdn)$'  : 'markdown',
                  \ }
  

• g:zv_disable_mapping - Disable default mappings.

  default: 0

• g:zv_get_docset_by - Set in which order and which criteria should be used when trying to match a pattern in g:zv_file_types.

default: ['file', 'ext', 'ft'].

e.g:

" Find matching pattern to the file type only:
let g:zv_get_docset_by = ['ft']

" Find matching pattern to the extension first, then to the file name 
" and finally to the type.
let g:zv_get_docset_by = ['ext', 'file', 'ft']

• g:zv_docsets_dir - Directory where are stored zeal's docsets for command completion purpose.

  default:

  let g:zv_docsets_dir = has('win32')
    \ ? $LOCALAPPDATA . '\Zeal\Zeal\docsets'
    \ : $HOME . '/.local/share/Zeal/Zeal/docsets'
  

• g:zv_keep_focus - Keep or not the focus on vim after executing zeal (Need wmtcrl to be installed and works only on GNU/Linux).

  default: 1

My configuration

nmap gzz <Plug>Zeavim
vmap gzz <Plug>ZVVisSelection
nmap <leader>z <Plug>ZVKeyDocset
nmap gZ <Plug>ZVKeyDocset<CR>
nmap gz <Plug>ZVOperator
let g:zv_keep_focus = 0
let g:zv_file_types = {
            \   'help'                : 'vim',
            \   'javascript'          : 'javascript,nodejs',
            \   'python'              : 'python_3',
            \   '\v^(G|g)ulpfile\.js' : 'gulp,javascript,nodejs',
            \ }
let g:zv_zeal_args = g:has_unix ? '--style=gtk+' : ''

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.

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.