How to use pman and custom help files in Vim with viewdoc plugin?

Question

When editing PHP files, I want to use help files from two sources:

• The vim help files in /etc/vim/bundle/yii-api-vim/doc/ from here .
• PHP pman pages with pman

If there is no help in the help files, try pman .

viewdoc help says that

You can have multiple documentation sources for the same file type and choose which one to use on the fly.

But this does not explain how to do this. The only function that comes close is handlers of a certain type of file, for example ViewDoc_{filetype}(topic, filetype, synid, have_context) . But I do not know how to implement such a function.

Open questions for me:

• How can I check inside this function if *.txt file exists in my specific directory?
• What should I return in order for viewdoc to open such a help file, if one exists?
• What should I return in order for viewdoc to open the pman page for a regular PHP function?

It would be useful to see an example of such a function.

Answer 1

I'm not an expert on vim script, so this may not be the perfect solution, but this is what worked for me.

First, create a custom viewdoc handler in the file viewdoc_pman.vim (which can be found in the ~ / .vim / bundle / viewdoc / plugin / directory if you are using the recommended pathogen setting).

 function ViewDoc_pman_custom(topic, filetype, synid, ctx) let l:tagpath = '/etc/vim/bundle/yii-api-vim/doc/tags' let l:shell = printf('grep %s %s', shellescape(a:topic,1), l:tagpath) let l:output = system(l:shell) if !v:shell_error return g:ViewDoc_help(a:topic, a:filetype, a:synid, a:ctx) else let l:ViewDoc_pman_old = function('ViewDoc_pman') return l:ViewDoc_pman_old(a:topic, a:filetype, a:synid, a:ctx) endif endfunction 

This function uses grep to find the specified subject line in the yii-api-vim tag file. If he finds this, he simply redirects the command to the default ViewDoc_help handler (it is assumed that you have already installed the yii-api-vim documentation so that it works correctly with standard help).

If grep finds nothing, it returns to calling the old php handler in the ViewDoc_pman function. Note that we cannot just call g: ViewDoc_pman directly, as this is the variable we are going to overwrite. We need to get the descriptor of the old function using function('ViewDoc_pman') and call it instead.

Finally, you need to find these two lines:

 let g:ViewDoc_pman = function('ViewDoc_pman') let g:ViewDoc_php = function('ViewDoc_pman') 

And replace them with these two:

 let g:ViewDoc_pman = function('ViewDoc_pman_custom') let g:ViewDoc_php = function('ViewDoc_pman_custom') 

This causes all php documentation requests to be redirected to our new custom handler, and not to the old ViewDoc_pman function.

If you do not want to edit the viewdoc_pman.vim file, you can put the viewdoc handler in your .vimrc file. Then, to set the g: ViewDoc_pman and g: ViewDoc_php variables, you need to add the following lines:

 autocmd VimEnter * let g:ViewDoc_pman = function('ViewDoc_pman_custom') autocmd VimEnter * let g:ViewDoc_php = function('ViewDoc_pman_custom') 

autocmd VimEnter forces the assignments to be executed after all plugins have been loaded, otherwise these variables are simply overwritten by the plugin and your custom handler will never be called.