updated for version 7.0001
diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt
new file mode 100644
index 0000000..882cd6a
--- /dev/null
+++ b/runtime/doc/if_perl.txt
@@ -0,0 +1,258 @@
+*if_perl.txt* For Vim version 7.0aa. Last change: 2004 May 01
+
+
+ VIM REFERENCE MANUAL by Sven Verdoolaege
+ and Matt Gerassimof
+
+Perl and Vim *perl* *Perl*
+
+1. Editing Perl files |perl-editing|
+2. Compiling VIM with Perl interface |perl-compiling|
+3. Using the Perl interface |perl-using|
+
+{Vi does not have any of these commands}
+
+The Perl interface only works when Vim was compiled with the |+perl| feature.
+
+==============================================================================
+1. Editing Perl files *perl-editing*
+
+Vim syntax highlighting supports Perl and POD files. Vim assumes a file is
+Perl code if the filename has a .pl or .pm suffix. Vim also examines the first
+line of a file, regardless of the filename suffix, to check if a file is a
+Perl script (see scripts.vim in Vim's syntax directory). Vim assumes a file
+is POD text if the filename has a .POD suffix.
+
+To use tags with Perl, you need a recent version of Exuberant ctags. Look
+here:
+ http://ctags.sourceforge.net
+
+Alternatively, you can use the Perl script pltags.pl, which is shipped with
+Vim in the $VIMRUNTIME/tools directory. This script has currently more
+features than Exuberant ctags' Perl support.
+
+==============================================================================
+2. Compiling VIM with Perl interface *perl-compiling*
+
+To compile Vim with Perl interface, you need Perl 5.004 (or later). Perl must
+be installed before you compile Vim. Vim's Perl interface does NOT work with
+the 5.003 version that has been officially released! It will probably work
+with Perl 5.003_05 and later.
+
+The Perl patches for Vim were made by:
+ Sven Verdoolaege <skimo@breughel.ufsia.ac.be>
+ Matt Gerassimof
+
+Perl for MS-Windows can be found at:
+http://www.perl.com/CPAN/ports/nt/Standard/x86/
+
+==============================================================================
+3. Using the Perl interface *perl-using*
+
+ *:perl* *:pe*
+:pe[rl] {cmd} Execute Perl command {cmd}. The current package
+ is "main".
+
+:pe[rl] << {endpattern}
+{script}
+{endpattern}
+ Execute Perl script {script}.
+ {endpattern} must NOT be preceded by any white space.
+ If {endpattern} is omitted, it defaults to a dot '.'
+ like for the |:append| and |:insert| commands. Using
+ '.' helps when inside a function, because "$i;" looks
+ like the start of an |:insert| command to Vim.
+ This form of the |:perl| command is mainly useful for
+ including perl code in vim scripts.
+ Note: This command doesn't work when the Perl feature
+ wasn't compiled in. To avoid errors, see
+ |script-here|.
+
+
+Example vim script: >
+
+ function! WhitePearl()
+ perl << EOF
+ VIM::Msg("pearls are nice for necklaces");
+ VIM::Msg("rubys for rings");
+ VIM::Msg("pythons for bags");
+ VIM::Msg("tcls????");
+ EOF
+ endfunction
+<
+
+ *:perldo* *:perld*
+:[range]perld[o] {cmd} Execute Perl command {cmd} for each line in the
+ [range], with $_ being set to the text of each line in
+ turn, without a trailing <EOL>. Setting $_ will change
+ the text, but note that it is not possible to add or
+ delete lines using this command.
+ The default for [range] is the whole file: "1,$".
+
+Here are some things you can try: >
+
+ :perl $a=1
+ :perldo $_ = reverse($_);1
+ :perl VIM::Msg("hello")
+ :perl $line = $curbuf->Get(42)
+<
+ *E299*
+Executing Perl commands in the |sandbox| is limited. ":perldo" will not be
+possible at all. ":perl" will be evaluated in the Safe environment, if
+possible.
+
+
+ *perl-overview*
+Here is an overview of the functions that are available to Perl: >
+
+ :perl VIM::Msg("Text") # displays a message
+ :perl VIM::Msg("Error", "ErrorMsg") # displays an error message
+ :perl VIM::Msg("remark", "Comment") # displays a highlighted message
+ :perl VIM::SetOption("ai") # sets a vim option
+ :perl $nbuf = VIM::Buffers() # returns the number of buffers
+ :perl @buflist = VIM::Buffers() # returns array of all buffers
+ :perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c'
+ :perl @winlist = VIM::Windows() # returns array of all windows
+ :perl $nwin = VIM::Windows() # returns the number of windows
+ :perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1
+ :perl ($success, $v) = VIM::Eval('&xyz') # $v: '' and $success: 0
+ :perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile>
+ :perl $curwin->SetHeight(10) # sets the window height
+ :perl @pos = $curwin->Cursor() # returns (row, col) array
+ :perl @pos = (10, 10)
+ :perl $curwin->Cursor(@pos) # sets cursor to @pos
+ :perl $curwin->Cursor(10,10) # sets cursor to row 10 col 10
+ :perl $mybuf = $curwin->Buffer() # returns the buffer object for window
+ :perl $curbuf->Name() # returns buffer name
+ :perl $curbuf->Number() # returns buffer number
+ :perl $curbuf->Count() # returns the number of lines
+ :perl $l = $curbuf->Get(10) # returns line 10
+ :perl @l = $curbuf->Get(1 .. 5) # returns lines 1 through 5
+ :perl $curbuf->Delete(10) # deletes line 10
+ :perl $curbuf->Delete(10, 20) # delete lines 10 through 20
+ :perl $curbuf->Append(10, "Line") # appends a line
+ :perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines
+ :perl @l = ("L1", "L2", "L3")
+ :perl $curbuf->Append(10, @l) # appends L1, L2 and L3
+ :perl $curbuf->Set(10, "Line") # replaces line 10
+ :perl $curbuf->Set(10, "Line1", "Line2") # replaces lines 10 and 11
+ :perl $curbuf->Set(10, @l) # replaces 3 lines
+<
+ *perl-Msg*
+VIM::Msg({msg}, {group}?)
+ Displays the message {msg}. The optional {group}
+ argument specifies a highlight group for Vim to use
+ for the message.
+
+ *perl-SetOption*
+VIM::SetOption({arg}) Sets a vim option. {arg} can be any argument that the
+ ":set" command accepts. Note that this means that no
+ spaces are allowed in the argument! See |:set|.
+
+ *perl-Buffers*
+VIM::Buffers([{bn}...]) With no arguments, returns a list of all the buffers
+ in an array context or returns the number of buffers
+ in a scalar context. For a list of buffer names or
+ numbers {bn}, returns a list of the buffers matching
+ {bn}, using the same rules as Vim's internal
+ |bufname()| function.
+
+ *perl-Windows*
+VIM::Windows([{wn}...]) With no arguments, returns a list of all the windows
+ in an array context or returns the number of windows
+ in a scalar context. For a list of window numbers
+ {wn}, returns a list of the windows with those
+ numbers.
+
+ *perl-DoCommand*
+VIM::DoCommand({cmd}) Executes Ex command {cmd}.
+
+ *perl-Eval*
+VIM::Eval({expr}) Evaluates {expr} and returns (success, val).
+ success=1 indicates that val contains the value of
+ {expr}; success=0 indicates a failure to evaluate
+ the expression. '@x' returns the contents of register
+ x, '&x' returns the value of option x, 'x' returns the
+ value of internal |variables| x, and '$x' is equivalent
+ to perl's $ENV{x}. All |functions| accessible from
+ the command-line are valid for {expr}.
+
+ *perl-SetHeight*
+Window->SetHeight({height})
+ Sets the Window height to {height}, within screen
+ limits.
+
+ *perl-GetCursor*
+Window->Cursor({row}?, {col}?)
+ With no arguments, returns a (row, col) array for the
+ current cursor position in the Window. With {row} and
+ {col} arguments, sets the Window's cursor position to
+ {row} and {col}. Note that {col} is numbered from 0,
+ Perl-fashion, and thus is one less than the value in
+ Vim's ruler.
+
+Window->Buffer() *perl-Buffer*
+ Returns the Buffer object corresponding to the given
+ Window.
+
+ *perl-Name*
+Buffer->Name() Returns the filename for the Buffer.
+
+ *perl-Number*
+Buffer->Number() Returns the number of the Buffer.
+
+ *perl-Count*
+Buffer->Count() Returns the number of lines in the Buffer.
+
+ *perl-Get*
+Buffer->Get({lnum}, {lnum}?, ...)
+ Returns a text string of line {lnum} in the Buffer
+ for each {lnum} specified. An array can be passed
+ with a list of {lnum}'s specified.
+
+ *perl-Delete*
+Buffer->Delete({lnum}, {lnum}?)
+ Deletes line {lnum} in the Buffer. With the second
+ {lnum}, deletes the range of lines from the first
+ {lnum} to the second {lnum}.
+
+ *perl-Append*
+Buffer->Append({lnum}, {line}, {line}?, ...)
+ Appends each {line} string after Buffer line {lnum}.
+ The list of {line}s can be an array.
+
+ *perl-Set*
+Buffer->Set({lnum}, {line}, {line}?, ...)
+ Replaces one or more Buffer lines with specified
+ {lines}s, starting at Buffer line {lnum}. The list of
+ {line}s can be an array. If the arguments are
+ invalid, replacement does not occur.
+
+$main::curwin
+ The current window object.
+
+$main::curbuf
+ The current buffer object.
+
+
+ *script-here*
+When using a script language in-line, you might want to skip this when the
+language isn't supported. But this mechanism doesn't work: >
+ if has('perl')
+ perl << EOF
+ this will NOT work!
+ EOF
+ endif
+Instead, put the Perl/Python/Ruby/etc. command in a function and call that
+function: >
+ if has('perl')
+ function DefPerl()
+ perl << EOF
+ this works
+ EOF
+ endfunction
+ call DefPerl()
+ endif
+Note that "EOF" must be at the start of the line.
+
+ vim:tw=78:ts=8:ft=help:norl: