kabbamine/zeavim.vim

Zeal for Vim

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.

zeavim.vim's Issues

Disabling default mappings disables all mappings

I love the plugin, however I'm having one issue. If I disable the default mappings with:

let g:zv_disable_mapping = 1

Then none of my custom mappings work, for example:

nmap <leader>d <Plug>Zeavim

does nothing when I press <leader>d. Is this expected? Should I just map to the commands?

nmap <leader>d :Zeavim<CR>

ZVMotion problems

Hi, thanks for the plugin. I have some problems to understand what ZVMotion does reading the docs. What is a text motion? Do you mean inserting a string in the command line?

I installed to play around, and I love it! But gz mapped to ZVMotion is doing nothing. gz gets interpreted as g@? Check my settings and the mappings they generate:

Feature request: Search docsets but not just a single doc

For example:

var http = require("http");

If I search for the word 'require', zeal will only search for javascript, but not docsets related to javascript.
Hope for searching docsets like dash.vim. Here is the docsets for dash.vim. Maybe it will be helpful. Thanks!

Incorrect docset name completion for opencv c++

Currently completion of opencv c++ is opencv_c++ (name read from docset source) which is invalid (see comment)

Although we can manually workaround with a configuration:
let g:zv_file_types = { 'cpp': 'cpp,cvcpp' }

But the docset completion should give either a correct keyword or nothing.

Builtin Vim alternative for Keyword/Selection Lookup

For example, by adding in .vim/ftplugin/lua.vim,

setlocal keywordprg=zeal\ lua:\
nnoremap <buffer> K K<CR>
xnoremap <buffer> K K<CR>

hitting K in a lua file looks up the Zeal doc for the keyword/selection.

Error occurs while search visual selection of '#'

Error detected while processing function zeavim#SearchFor[10]..<SNR>164_Zeal:
E194: No alternate file name to substitute for '#': !zeal 'vim:#' 2> /dev/null &

vmap for ZVVisSelection is not working

It is really weird, the mapping

vmap <silent> <unique> <leader>z <plug>ZVVisSelection

is not working for me, I have to call zeavim#searchFor() directly, just like the following:

vmap <silent> <unique> <Leader>z :call zeavim#SearchFor('', '', 'v')<CR>

I have no idea what's going on here. But, it works after the key mapping change.

My Vim is MacVim 8.0.1592
My OS is MacOS 10.3.3

Have a setting to turn off wmctrl

I have my own script to run zeal and autofocus it (I use a tiling window manager) and wmctrl interferes with that. For the moment I worked around it by uninstalling wmctrl, but the proper solution is to have a configuration option ti turn it off in this plugin.

error

处理 /home/askding/.vim/bundle/zeavim.vim/plugin/zeavim.vim 时发生错误:
第 20 行:
E21: 不能修改，因为选项 'modifiable' 是关的: fileformat=unix

Duplicate mapping

Hi

After release 2.0, vim is complaining about the mapping in line 29, because it's can be already mapped in line 26 if you don't have any mapping to 'Zeavim'

Vim view goes black when <leader>z executed

I'm not sure why it's happening. But all the lines goes black. when i move the cursor between lines, then the code is showing.

nnoremap issue

trying to use zeavim.vim per https://zealdocs.org/usage.html

I did: :nnoremap gz :!zeal "<cword>"&<CR><CR> under vim

then I move my cursor to a function say 'printf' and hit 'gz' in vim, the zeal will find printf as expected, however I saw below output inside vim:

zeal.core.applicationsingleton: Singleton ID: lk9h--bESW50Rdi5tuyR-2VFhA25o8UAif9eOv5nuHk
                                                                                              zeal.core.applicationsingleton: Starting as a secondary instance.

use 0.6.1 on ubuntu 18.04

Use dash-plugin protocol by default

It may be interesting to use dash-plugin:// protocol by default and execute zeal's binary only if the option g:zv_zeal_executable is not empty (For the ones using a portable version for example).

The only benefit from using the url protocol is that zeavim will be compatible with dash in mac and velocity in windows.

I let the question in suspend so if anyone is interested, let me know.

Default docset directory

Zeal docs default to ~/.local/share/zeal/docsets
I cannot find the exact commit that introduced this change but found this issue as reference
zealdocs/zeal#317

Zeal not found

I have zeal installed under c:\Program Files\Zeal\zeal.exe but the plugin can not find it:

"Zeal is not present on the system or his location is not defined"

Zeavim starts Zeal in foreground

Hi. I'm curious if I am misunderstanding something: When I start Zeal through zeavim, the Zeal window is blocking Vim. Is that by intention?

I'm on Vim 8.0.427 on Arch Linux. This behaviour happens with both vim and gvim. I use the following settings:

let g:zv_disable_mapping = 1
let g:zv_zeal_args = '--style=gtk+'
let g:zv_file_types = {
    \ 'help' : 'vim',
    \ 'python' : 'python 3',
    \ }

nmap gzz <plug>Zeavim
xmap gzz <plug>ZVVisSelection
nmap gz <plug>ZVMotion

I would expect that the Zeal window opens as a background process, such that I could read the docs while editing the file. The current behaviour requires me to close the Zeal window before I continue editing the file.

autoloadize

Dear Kabb,

How about exporting the global functions into the .vim/autoload (instead of .vim/plugin) folder ? These would then go by the name zeavim#ZVKeyword() ... and alike. Good practice to keep startup times at bay. Though of course in this plugin miniscule.

autohotkey words cannot be found

autohotkey words are not found because zeavim sends(leader z) for ex:
autohotkey:SetWorkingDir
instead
ahk:SetWorkingDir
How to change it?

Syntax error on executing <leader>z

/bin/bash: -c: line 0: syntax error near unexpected token `&'
/bin/bash: -c: line 0: `zeal 'c++:cout' 2> /dev/null &&  &'

Visual selection in a buffer with only one line

When using the command Zeavim on a visual selection and the current buffer contains only one line, the command acts like in normal mode.

The actual process for determining the vim mode is quite tricky here, and I should find another way.

add support to wordpress

wordpress plugin use php.wordpress for the filetype, is there a way to convert php.wordpress to wordpress before loading zeal?

On windows: "> was unexpected at this time."

I just installed zeal on windows, and added to path. Doing a :!zeal opens zeal. I did not modify my configuration for zeavim.

When editing a cpp file, I press <leader>z, and the screen flickers shortly, but zeal stays closed. I could decypher what is shown during the flicker (in a command window):

> was unexpected at this time.

Any idea how to debug?