" put the cursor over a perl function and try backslash-pf to see perldoc
:nmap <Leader>pf :!perldoc -f <cword><CR>

" put the cursor over a perl module name and try backslash-pd to see perldoc
:nmap <Leader>pd :e `perldoc -ml <cword>`<CR>
" see ':help mapleader' for more info... default is backslash.

CommentsEdit

Here's something similar I use, with these improvements on original post:

1. Only sets up the mapping when editing perl files
2. Sets up 1 smart mapping that automatically works for perl functions as well as modules
3. Uses vim's build-in keyword definition feature instead of defining a new mapping

In your .vimrc add these 2 lines:

autocmd BufEnter *.pl,*.pm,*.cgi let oldkp=&kp | set keywordprg=perl \ -e\ $c=shift;exec\"perldoc\".($c=~/^[a-z]+$/?\"\ -f\ \":\"\ \").$c'
autocmd BufLeave *.pl,*.pm,*.cgi let &keywordprg=oldkp

Then when editing a perl file you can use perl's built-in keyword definition mapping (capital K == shift+k) when under a perl function or module to see it's POD.

See :help K.

Doesn't work. This is the error message I get.

Error detected while processing BufEnter Auto commands for "*.pl":
E518: Unknown option: \ -e\ $c=shift;exec"perldoc".($c=~/^[a-z]+$/?"\ -f\ ":"\ ").$c'

Try this:

autocmd BufEnter *.pl,*.pm,*.cgi setlocal keywordprg=perl\ -e'$c=shift;exec\"perldoc\ \".(/::/?\"\":\"-f\").\"\ $c\"'

(You don't need the BufLeave with setlocal)

It's clumsy. If you try to look at docs for Modules like CGI or DBI perldoc -f will still be called. You have to press enter once or twice before seeing the desired documentation and once or twice afterwards, depending on various conditions.

If there is a vimscript that handles this better I'd like to see it. Something that checks perldoc's exit code and tries again probably.

Try this:

autocmd FileType perl :setlocal keywordprg=perl\ -e\ '$c=shift;exec\"perldoc\ $c\ \|\|\ perldoc\ -f\ $c\ \|\|\ echo\"'

This will try the keyword as a module first and if that fails it will call perldoc again with -f on the assumption that we're looking at a function. If that fails then echo an empty string to avoid some wierdities.

However. It's still clumsy. You have to press q and then any key to get back to your buffer. Is there anyway to get this output into a help buffer?

Try this:

autocmd FileType perl noremap K :!echo <cWORD> <cword> <bar> perl -e '$line = <STDIN>; if ($line =~ /(\w+::\w+)/){exec("perldoc $1")} elsif($line =~ /(\w+)/){exec "perldoc -f $1 <bar><bar> perldoc $1"}'<cr><cr>

This will work on:

use MIME::Lite;
use Encode;
print("El Barto was here")
$msg->send;