6

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.

Michael Härtl
  • 8,428
  • 5
  • 35
  • 62
  • What did you try? How did it fail? – romainl Jul 16 '13 at 07:24
  • I didn't try anything because a) i'm not confident in vimscript and b) from the manual i wouldn't even know what to return so that it opens my help files in my specific directory. – Michael Härtl Jul 16 '13 at 07:30
  • 1
    You might want to ask for examples on the [issue tracker](https://code.google.com/p/vim-plugin-viewdoc/issues/list). I Don't think enough people have used this plugin to write an example. – FDinoff Jul 21 '13 at 18:43
  • 1
    Link to @MichaelHärtl issue on the tracker https://code.google.com/p/vim-plugin-viewdoc/issues/detail?id=12 – FDinoff Jul 23 '13 at 03:28

1 Answers1

3

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.

James Holderness
  • 22,721
  • 2
  • 40
  • 52
  • Thanks, this solution really works! But it requires to change the plugin files what i want to avoid. According to the help it should also work to create a `ViewDoc_php` function in your `.vimrc` (see [here](https://github.com/powerman/vim-plugin-viewdoc/blob/master/doc/viewdoc.txt#L378)). This didn't work at all for me: Any function in my `.vimrc` was ignored. Did this work for you somehow? – Michael Härtl Jul 25 '13 at 06:43
  • I did briefly try getting the code to work in .vimrc, but the problem was the need to overwrite the *g:ViewDoc\_php* and *g:ViewDoc\_pman* variables. From what I could tell .vimrc gets loaded before the plugins, so those variables aren't defined yet. But I will do some more investigation and see if I can find a way. – James Holderness Jul 25 '13 at 09:56
  • Also see [this issue](http://code.google.com/p/vim-plugin-viewdoc/issues/detail?id=13). – Michael Härtl Jul 25 '13 at 10:35
  • Sorry for the delay in replying. My computer isn't dealing well with the heat at the moment and it tends to shut itself down every time I start up my Linux VM. However, I've just had a chance to test, and that `autocmd VimEnter` trick you found seems to be solution. I suspect you've already figured that out, but I've updated my answer anyway for future reference. Also, thanks for the bounty! – James Holderness Jul 25 '13 at 15:48
  • Your example should be updated for compatibility with vim-7.4.260, see https://code.google.com/p/vim-plugin-viewdoc/issues/detail?id=26 – Powerman May 15 '14 at 23:51