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

Question

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

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

If there's no help available from the help files it should try pman.

The viewdoc plugin's help claims that

You can have several documentation sources for same file type, and choose which one should be used on-the-fly.

But it does not explain, how to do this. The only feature that comes close are handlers for a specific filetype, like ViewDoc_{filetype}(topic, filetype, synid, have_context). But I don't know how to implement such a function.

Open questions to me are:

• How can I check inside that function if a *.txt file exists in my specific directory?
• What should I return to let viewdoc open such a help file if it exists?
• What should I return to let viewdoc open a pman page for a ordinary PHP function?

It would be helpful to see an example for such a function.

Answer 1

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

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

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 look for the specified topic string in the yii-api-vim tags file. If it finds it there, it just forwards the command to the default ViewDoc_help handler (this is assuming you've already installed the yii-api-vim documentation so that it works correctly with the standard help).

If grep doesn't find anything, then it falls back to calling the old php handler in the ViewDoc_pman function. Note that we can't just call g:ViewDoc_pman directly since that is a variable that we are about to overwrite. We need to get a handle to the old function using function('ViewDoc_pman') and call that 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 forces all php documentation queries to be forwarded to our new custom handler rather than the old ViewDoc_pman function.

If you prefer not to edit the viewdoc_pman.vim file, you can put the viewdoc handler in your .vimrc file instead. Then to set the g:ViewDoc_pman and g:ViewDoc_php variables, you'll 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')

The autocmd VimEnter forces the assignments to happen after all plugins have been loaded, otherwise those variables would just be overwritten by the plugin and your custom handler would never be called.