*perlsupport.txt*                Perl Support               November 23 2008

Perl Support                                      *perl-support* *perlsupport*

                              Plugin version 3.9
                        for Vim version 6.0 and above
                       Fritz Mehner  <mehner@fh-swf.de>

Perl Support implements a Perl-IDE for Vim/gVim. It is written to considerably
speed up writing code in a consistent style.  This is done by inserting
complete statements, comments, idioms, code snippets, templates, and POD
documentation.  Reading perldoc is integrated.  Syntax checking, running a
script, running perltidy,  running perlcritics, starting a debugger and a
profiler can be done with a keystroke.  
This plugin can be used with Vim version 7.x . Most features should work with
Vim version 6.x.

 1.      Usage with GUI                   |perlsupport-usage-gvim|
 1.1      Menu 'Comments'                 |perlsupport-comments|
 1.1.1     Append aligned comments        |perlsupport-aligned-comm|
 1.1.2     Comment templates              |perlsupport-comm-templates|
 1.1.3     Toggle comment                 |perlsupport-comm-toggle|
 1.1.4     Comment out a block of code    |perlsupport-comm-block|
 1.1.5     Uncomment a block of code      |perlsupport-uncomm-block|
 1.1.6     KEYWORD + comment              |perlsupport-comm-keywords|
 1.2      Menu 'Statements'               |perlsupport-statements|
 1.2.1     Normal mode, insert mode       |perlsupport-stat-norm-ins|
 1.2.2     Visual mode                    |perlsupport-stat-visual|
 1.2.3     Code snippets                  |perlsupport-stat-snippets|
 1.3      Menu 'Idioms'                   |perlsupport-idioms|
 1.3.1      Stub subroutine               |perlsupport-stub-sub|
 1.3.2      Opening files                 |perlsupport-open-files|
 1.4      Menu 'Regex'                    |perlsupport-regex|
 1.4.1     Compose regular expressions    |perlsupport-regex-compose|
 1.4.2     Explain regular expression     |perlsupport-regex-explain|
 1.4.3     Match                          |perlsupport-regex-match|
 1.5      Menu 'CharCls'                  |perlsupport-charcls|
 1.6      Menu 'File-Tests'               |perlsupport-filetests|
 1.7      Menu 'Spec-Var'                 |perlsupport-specvar|
 1.8      Menu 'POD'                      |perlsupport-pod|
 1.8.1    Menu 'invisible POD'            |perlsupport-pod-invisible|
 1.8.2    Run podchecker                  |perlsupport-podchecker|
 1.9      Menu 'Run'                      |perlsupport-run|
 1.9.1     Run script                     |perlsupport-run-script|
 1.9.2     Check syntax                   |perlsupport-syntax-check|
 1.9.3     Command line arguments         |perlsupport-cmdline-args|
 1.9.4     Perl command line switches     |perlsupport-perl-switches|
 1.9.5     Debug                          |perlsupport-run-debug|
 1.9.6     Read perldoc                   |perlsupport-perldoc|
 1.9.7     Generate Perl module list      |perlsupport-module-list-generation|
 1.9.8     Show installed Perl modules    |perlsupport-module-list|
 1.9.9     Run perltidy                   |perlsupport-perltidy|
 1.9.10    Run SmallProf                  |perlsupport-profile|
 1.9.11    Run perlcritic                 |perlsupport-perlcritic|
 1.9.12    Save buffer with timestamp     |perlsupport-timestamp|
 1.9.13    Hardcopy                       |perlsupport-hardcopy|
 1.9.14    Settings                       |perlsupport-settings|
 1.9.15    Xterm size                     |perlsupport-xterm|
 1.9.16    Change Output Destination      |perlsupport-output|
 1.10    Help                             |perlsupport-help|
 2.      Usage without GUI                |perlsupport-mappings|
 3.      Function Keys                    |perlsupport-function-keys|
 4.      Customization and configuration  |perlsupport-customization|
 4.1      Files                           |perlsupport-custom-files|
 4.2      Global variables                |perlsupport-custom-variables|
 4.3      The root menu                   |perlsupport-custom-root|
 4.4      Navigate through PODs           |perlsupport-custom-navigate|
 4.5      Tabulator width                 |perlsupport-custom-tab|
 4.6      Syntax based folding            |perlsupport-folding|
 4.7      System-wide installation        |perlsupport-system-wide|
 5.      Template files and tags          |perlsupport-tempfiles|
 5.1      Template files                  |perlsupport-tempfiles|
 5.2      Tags                            |perlsupport-tags|
 5.3      Perl::Tags                      |perlsupport-perltags|
 6.      Perl Dictionary                  |perlsupport-dictionary|
 7.      Optional Dependencies            |perlsupport-dependencies|
 8.      Compiling Vim                    |perlsupport-compile-vim|
 9.      MS-Windows particularities       |perlsupport-windows|
 10.     Troubleshooting                  |perlsupport-troubleshooting|
 11.     Release Notes / Change Log       |perlsupport-release-notes|
 12.     Credits                          |perlsupport-credits|

 How to add this help file to vim's help  |add-local-help|

==============================================================================
1.  USAGE WITH GUI  (gVim)                            *perlsupport-usage-gvim*
==============================================================================

If the root menu 'Perl' is not visible call it with the item
"Load Perl Support" from the standard Tools-menu.
The item "Unload Perl Support" can be used to unload the Perl root menu.
See also |perlsupport-custom-root|.

------------------------------------------------------------------------------
1.1 MENU 'Comments'                                     *perlsupport-comments*
------------------------------------------------------------------------------

1.1.1 APPEND ALIGNED COMMENTS TO CONSECUTIVE LINES  *perlsupport-aligned-comm*
--------------------------------------------------
In NORMAL MODE the menu item
 'Line End Comm.'
will append a comment to the current line.

In VISUAL MODE this item will append aligned comments to all marked lines.
Marking the 3 lines

my  $x11       = 11;
my  $x1111     = 1111;

my  $x11111111 = 11111111;

and choosing 'Line End Comm.' will yield

my  $x11       = 11;                            # |
my  $x1111     = 1111;                          #

my  $x11111111 = 11111111;                      #

The cursor position above is marked by '|' . Empty lines will be ignored.

The default starting column is 49 ( = (multiple of 2,4, or 8) + 1 ).  This can
be changed by setting a global variable in the file .vimrc , e.g. :

  let g:Perl_LineEndCommColDefault    = 45

The starting column can also be set by the menu item 'Comments->Set End Comm.
Col.' . Just position the cursor in an arbitrary column (column number is
shown in the Vim status line) and choose this menu item.  This setting is
buffer related.

If the cursor was at the end of a line you will be asked for a column number
because this position is most likely not the desired starting column.
Your choice will be confirmed.

ALIGNMENT OF COMMENTS
---------------------
After some copy/paste/change actions the comments may be misaligned:

my  $x11   = 11;                                      # comment1 
my  $x111  = 1111;                               # comment 2

my  $x1111 = 11111111;                    # comment 3

NORMAL MODE: The menu item 'Align Line End Comm.' aligns the comment (if any)
to the actual current comment starting column.
VISUAL MODE: All comments in the marked area will be aligned.


1.1.2  COMMENT TEMPLATES                          *perlsupport-comm-templates*
------------------------
Frame comments, function descriptions and file header comments are read as
templates from the appropriate files (see |perlsupport-tempfiles|).

1.1.3 TOGGLE COMMENT                                *perlsupport-comm-toggle*
---------------------
The comment sign # can be set or removed at the beginning of the current line.
A single line needs not to be marked.

A marked block 

 my $x11       = 11;
 
 #my $x1111     = 1111;
 #  print "\n";
   #print "\n";

will be changed into (and vice versa)

 #my $x11       = 11;
 #
 my $x1111     = 1111;
   print "\n";
   print "\n";

Whitespaces in front of the hash sign will be preserved.

1.1.4 COMMENT OUT A BLOCK OF CODE                     *perlsupport-comm-block*
---------------------------------
In normal mode the menu item 'comment block' inserts an empty POD block which
can be used like a C preprocessor directive for conditional compilation.
Statements inside will not be executed by the Perl interpreter.  This is
usually done to temporarily block out some code. 

=begin  BlockComment  # BlockCommentNo_1

=end    BlockComment  # BlockCommentNo_1

=cut

In visual mode a block of code like

  print "x11 = $x11\n";
  print "x22 = $x22\n";

will be surrounded by the above construct:

=begin  BlockComment  # BlockCommentNo_2

  print "x11 = $x11\n";
  print "x22 = $x22\n";

=end    BlockComment  # BlockCommentNo_2

=cut

The label names like BlockCommentNo_2 are automatically inserted into the
comments.  The trailing numbers are automatically incremented if you apply the
command again.  These numbers can be changed by the user (both!).  The next
number will be one above the highest number found in the current buffer.  The
empty lines between the POD statements are necessary.

A corresponding label can be found by searching with the vim star command (*).
All labels can be found with a global search like :g/BlockCommentNo_/ or
:g/BlockCommentNo_\d\+/.

1.1.5 UNCOMMENT A BLOCK OF CODE                     *perlsupport-uncomm-block*
-------------------------------
The menu item 'uncomment block' removes such a construct if the cursor is in
the middle of such a block or on the line with '=begin ...'. Nested constructs
will be untouched.

1.1.6 KEYWORD+comment                              *perlsupport-comm-keywords*
---------------------
Preliminary line end comments to document (and find again) places where work
will be resumed shortly, like

   # :TODO:12.05.2004:Mn: <your comment>

Usually not meant for the final documentation.

------------------------------------------------------------------------------
1.2  MENU 'Statements'                                *perlsupport-statements*
------------------------------------------------------------------------------

1.2.1  NORMAL MODE, INSERT MODE.                   *perlsupport-stat-norm-ins*
--------------------------------
An empty statement will be inserted and properly indented. The item 'if{}'
will insert an if-statement:

if (  ) {
}

The opening curly brace is on the same line as the keyword introducing it.  To
place the brace on a new line set the appropriate global variable in .vimrc :

  let g:Perl_BraceOnNewLine     = "yes"   

The default values is "no".  This flag applies to all structural blocks,
including subroutines. 

1.2.2  VISUAL MODE.                                  *perlsupport-stat-visual*
-------------------
The highlighted area

xxxxx
xxxxx

can be surrounded by one of the following statements ( '|'
marks the cursor position after insertion):

  +----------------------------------------------------------+
  |                                                          |
  |  do {                                                    |
  |    xxxxx                                                 |
  |    xxxxx                                                 |
  |  }                                                       |
  |  while ( | );       # -----  end do-while  -----         |
  |                                                          |
  +--------------------------+-------------------------------+
  |                          |                               |
  |  for ( my $|; ;  ) {     |  foreach my $| (  ) {         |
  |    xxxxx                 |    xxxxx                      |
  |    xxxxx                 |    xxxxx                      |
  |  }                       |  }                            |
  |                          |                               |
  +--------------------------+-------------------------------+
  |                          |                               |
  |  if ( | ) {              |  if ( | ) {                   |
  |    xxxxx                 |    xxxxx                      |
  |    xxxxx                 |    xxxxx                      |
  |  }                       |  }                            |
  |                          |  else {                       |
  |                          |  }                            |
  |                          |                               |
  +--------------------------+-------------------------------+
  |                          |                               |
  |  unless ( | ) {          |  unless ( | ) {               |
  |    xxxxx                 |    xxxxx                      |
  |    xxxxx                 |    xxxxx                      |
  |  }                       |  }                            |
  |                          |  else {                       |
  |                          |  }                            |
  |                          |                               |
  +--------------------------+-------------------------------+
  |                          |                               |
  |  until ( | ) {           |  while ( | ) {                |
  |    xxxxx                 |    xxxxx                      |
  |    xxxxx                 |    xxxxx                      |
  |  }                       |  }                            |
  |                          |                               |
  +--------------------------+-------------------------------+
  |                          |                               |
  |  {                       |  elsif ( | ) {                |
  |    xxxxx                 |    xxxxx                      |
  |    xxxxx                 |    xxxxx                      |
  |  }                       |  }                            |
  |                          |                               |
  +--------------------------+-------------------------------+

The whole statement will be indented after insertion.

The foreach loop uses a lexical iterator variable becaues Perl does this
anyway.


1.2.3  CODE SNIPPETS                                *perlsupport-stat-snippets*
--------------------
Code snippets are pieces of code which are kept in separate files in a special
directory. File names are used to identify the snippets.
The snippet directory has to be created by the user
( $HOME/.vim/codesnippets-perl is the default).
Snippets are managed with the 3 entries

   Perl -> Statements -> read  code snippet
   Perl -> Statements -> write code snippet
   Perl -> Statements -> edit  code snippet

from the Statements submenu.

Creating a new snippet:
-----------------------
When nothing is marked, "write code snippet" will write the whole buffer
to a snippet file, otherwise the marked area will be written to a file.

Insert a snippet:
-----------------
Select the appropriate file from the snippet directory ("read code snippet").
The inserted lines will be indented.

Indentation / no indentation
----------------------------
Code snippets are normally indented after insertion. To suppress indentation
add the file extension "ni" or "noindent" to the snippet file name, e.g.

  parameter_handling.pl.noindent

There are some snippets belonging to this plugin package. These are examples.
Add your own.

------------------------------------------------------------------------------
1.3  MENU 'Idioms'                                        *perlsupport-idioms*
------------------------------------------------------------------------------

1.3.1  STUB SUBROUTINE                                  *perlsupport-stub-sub*
----------------------
In normal mode the item 'subroutine' asks for a subroutine name and creates a
stub subroutine with one parameter:

  sub xxx {
    my  ($par1) = @_;
    
    return ;
  } # ----------  end of subroutine xxx  ----------


In visual mode with a few lines marked this item will enclose these lines in
a subroutine and generate a call to this subroutine. The lines 

  print "x11 = $x11\n";
  print "x22 = $x22\n";
  print "x33 = $x33\n";

will be changed into

  abc();

  sub abc {
    my  ($par1) = @_;
    print "x11 = $x11\n";
    print "x22 = $x22\n";
    print "x33 = $x33\n";
    return ;
  } # ----------  end of subroutine abc  ----------

The further adaption is left to the user.

1.3.2  OPENING FILES                                  *perlsupport-open-files*
--------------------
All declarations beginning with 'my' and the multi-line statements (subroutine,
open input file / output file / pipe) will be inserted below the current line.
Everything else will be inserted at the cursor position.

The entries 'open input file', 'open output file' and 'open pipe' ask for the
name of a file handle. After the insertion of the statements

  my  $INFILE_file_name = '';     # input file name
  
  open  my $INFILE, '<', $INFILE_file_name
      or die  "$0 : failed to open  input file $INFILE_file_name : $!\n";
  
  
  close  $INFILE
      or warn "$0 : failed to close input file $INFILE_file_name : $!\n";

the 'Idioms'-menu will be extended with an item for the new handle:

  <$INFILE>

After the insertion of the statements for an output file the 'Idioms'-menu
will be extended by a new print statement for the new handle, e.g.

  print $OUTFILE "\n";

Multi-line inserts will be indented after insertion.

The menu items and hotkeys for opening a file or a pipe have visual mode. When
a block is selected the code for opening a file/pipe will be inserted above
this block, the close statement will be inserted below.

PERL-BEST-PRACTICES-STYLE
-------------------------
The Perl operators m, s, and tr will be generated by the menu items from the
'Idioms'-menu in the traditional form using slashes: 

  $ =~ m//
  $ =~ s///
  $ =~ tr///

You can switch to
 
  $ =~ m{}xm
  $ =~ s{}{}xm
  $ =~ tr{}{}xm

by setting a global variable in the file '~/.vimrc' :

  let s:Perl_PBP  = 'yes'

The default value is 'no'.

------------------------------------------------------------------------------
1.4  MENU 'Regex'                                          *perlsupport-regex*
------------------------------------------------------------------------------

1.4.1  COMPOSE REGULAR EXPRESSIONS                 *perlsupport-regex-compose*

----------------------------------
In NORMAL and INSERT MODE the shown items will be inserted at the cursor
position.

In VISUAL MODE the following entries and all entries from the
'extended Regex' submenu will surround the marked area 'xxx' :

    ()    :      (xxx)
    (|)   :      (xxx|)
    []    :      [xxx]
    {}    :      {xxx}
    {,}   :      {xxx,}

1.4.2  EXPLAIN REGULAR EXPRESSION                  *perlsupport-regex-explain*
---------------------------------
If the Perl module YAPE::Regex::Explain is installed a regular expression
can be explained to you. 
Just mark the expression (v-mode) and use the menu entry 'explain Regex' or
the hotkey '\xe'. 
You also can pick up a complete line containing a regular expression with the
menu entry 'pick up regex' in normal mode. In this case leading and trailing
whitespaces will be removed.
Flags for the operator m/// can be picked up with  menu entry 'pick up flags'.

The regex will now be explain in a new buffer called 'REGEX-EXPLAIN'. This
buffer is not related  to a file and will not be written, but the content can
be printed with the hardcopy entry in the run-menu. A regular explain can span
several lines.
In order to use this feature you need a Vim binary with Perl interface
compiled in (see |perl|) and YAPE::Regex::Explain must be installed,  of
course.

1.4.3  MATCH                                         *perlsupport-regex-match*
------------
If you have a Vim binary with Perl interface compiled in (see |perl|) you can
test regular expressions very easily. This can be done in two ways.

(1) Visual mode. Pick up a regular expression by selecting the appropriate
string (v-mode; e.g.  inside the m// operator) and use the menu entry 'pick up
regex'.  Pick up flags the same way with 'pick up flags'. Now pick up a string
as target with 'pick up string' and select the menu entry 'match'. The regular
expression, the target and the match are shown in a new window called
REGEX-TEST: 

  REGEXP = m{([\w\s]+)(jumped)(.{1,6})([\w\s]+)}
  
  STRING    [  0, 53] = ### The quick brown fox jumped over the lazy dog. ###
  prematch  [  0,  3] = ###
  MATCH     [  3, 45] =   | The quick brown fox jumped over the lazy dog|
  postmatch [ 48,  5] =                                                 . ###
  
  $1        [  3, 21] =   | The quick brown fox |
  $2        [ 24,  6] =                         jumped
  $3        [ 30,  6] =                              | over |
  $4        [ 36, 12] =                                     the lazy dog
  
In addition the match will be highlighted in most cases. The match is done as
  $string =~ m{(?flags:$regexp)}
by the Perl interface. For the flags see|perlsupport-regex-flags|). 
The brackets after a match object contain the starting position (starting with
0) and the length of the object. Objects starting or ending with one or more
spaces are enclosed in vertical bars.

Multiline regular expressions (like the string inside the braces below) are
allowed. They work properly if the flag 'x' is set.

  regexp     = m{ \d+
                  /   # a/b
                  \d+
                  }x

Multiline strings are also allowed.  The regular expression '(\n+)$' matches
consecutive linefeeds at the end of a string or inside a string when used with
the flag 'm'.  The string in the following example consists of the 6 lines
from 'aaaa' to 'eeee'. The second, third, and fourth line contains 1 to 3
tabulators each (tab width is 2). The fifth line line is empty: 

  aaaa
  bb  bb
  cc    cc
  dd      dd
  
  eeee

With the flag 'm' matching gives the following visualization:

  REGEXP = m{(\n+)$}m
  
  lines : 6           = |1.. |2... |3.... |4.....  |6..
  STRING    [  0, 32] = aaaa$bb~bb$cc~~cc$dd~~~dd$$eeee$
  prematch  [  0, 25] = aaaa$bb~bb$cc~~cc$dd~~~dd
  MATCH     [ 25,  1] =                          $
  postmatch [ 26,  6] =                           $eeee$
  
  $1        [ 25,  1] =                          $
  
  
  Control character replacement: \n -> '$'   \t -> '~'

The linefeeds inside the string have been replace by dollar signs, the
tabulators have been replaced by the tilde. A ruler line will be shown. The
start of some lines are marked with the line number (depending on the line
length).
The control character replacements can be changed on the command line, e.g.:

  :RegexSubstitutions '# '

or by changing the defaults in the file '.vimrc'

  let g:Perl_PerlRegexSubstitution   = '# '

Linefeeds will now be replaced by '#' (the first character of the given pair),
tabulators will be replaced by a space. Control characters are not allowed as
replacements.

Last parenthesized submatch ($+) and  most-recently-closed capturing
parenthesis submatch ($^N). If the two results differ both are displayed:

  REGEXP = m{(Version: (.*)|Revision: (.*))}
  
  STRING    [  0, 25] = ##   Revision:    5-6-pre 
  prematch  [  0,  5] =|##   |
  MATCH     [  5, 20] =      Revision:    5-6-pre
  
  $1        [  5, 20] =      Revision:    5-6-pre
  $2        undefined
  $3        [ 15, 10] =               |   5-6-pre|
  
  $+            [ 10] =|   5-6-pre|
  $^N           [ 20] = Revision:    5-6-pre


(2) Normal mode. You can use a scratch buffer or a scratch area to test your
regular expressions. Just write the naked regular expression in one line and
the string on the next line:

  ([\w\s]+)(jumped)(.{1,6})([\w\s]+)
  ### The quick brown fox jumped over the lazy dog. ###

Now select 'pick up regex', 'pick up string', and 'match' in normal mode
or use the hotkeys \xr, \xs, and \xm .
Leading and trailing whitespaces are removed from the regex and target string
if picked up in normal mode. If one of these strings has such whitespaces pick
it up in visual mode.

The picked up regular expression, the string, and the flags are kept in
internal variables. After a change you have just to renew the changed item.
The variable for the regular expression and for the flags is also used by the
menu entry 'explain regex' (see|perlsupport-regex-explain|).

Pick up flag(s)                                      *perlsupport-regex-flags*

The menu item 'pick up flag(s)' asks for one of the regular expression flags
'imsx' or any combination of them (hotkeys \xf ). You can also mark flags in
visual mode and pick the selection up. Characters other than the allowed flags
will be removed.

LIMITATION. Regular expressions with  match-time code evaluation can not be
handled in the current version.

------------------------------------------------------------------------------
1.5  MENU 'CharCls'                                    *perlsupport-charcls*
1.6  MENU 'File-Tests'                                 *perlsupport-filetests*
1.7  MENU 'Spec-Var'                                   *perlsupport-specvar*
------------------------------------------------------------------------------

The entries from these menus will be inserted at the cursor position.

------------------------------------------------------------------------------
1.8  MENU 'POD'                                              *perlsupport-pod*
------------------------------------------------------------------------------

Most entries insert POD commands below the cursor position, e.g.

  =pod



  =cut

The entries 'POD->html', 'POD->man', 'POD->text' call the appropriate
translator which will generate the desired document from the current buffer.

The plugin taglist.vim (Yegappan Lakshmanan) can be expanded for POD
navigation. See |perlsupport-custom-navigate|.

1.8.1  MENU 'invisible POD'                        *perlsupport-pod-invisible*
---------------------------
These menu entries insert "invisible" POD sections as suggested in Damian
Conway's book "Perl Best Practices", e.g.

  =for Improvement: <keyword>
  <single paragraph>

  =cut

In visual mode these menu entries will surround the marked block with the
appropriate construct. The '=for' line will be put before the first nonempty
line of the marked block. 

The text in the single paragraph will be ignored by the compiler and by a POD
formatter. This can be used to embed extended pieces of internal
documentation. For the paragraph to be invisible there must not be an empty
line between =for ... and the following paragraph.

The four formatter names "Improvement", "Optimization", "Rationale", and
"Workaround" are just suggestions. You can choose additional ones.
The <keyword> is a short explanation which makes navigation with taglist
easier. See |perlsupport-custom-navigate|.
Please note the colon after the "formatter name". It is needed for parsing
this construct.

1.8.2  RUN PODCHECKER                                 *perlsupport-podchecker*
---------------------
The current buffer will be run through the application podchecker to check the
syntax of the embedded POD or of a POD format documentation file (see
podchecker(1) and Pod::Checker).
Podchecker always reports errors. Printing warnings can be turned on and off
with the options -warnings/-nowarning . The default is to print warnings.  To
turn the warnings of put the following line in the file .vimrc :
 
  let g:Perl_PodcheckerWarnings      = "no"


------------------------------------------------------------------------------
1.9  MENU 'Run'                                              *perlsupport-run*
------------------------------------------------------------------------------

1.9.1  RUN SCRIPT                                     *perlsupport-run-script*
-----------------
Run the script in the current buffer.  The output destination can be chosen
with the menu item 'Run->output: ...'.  There are 3 choices: VIM command
line, seperate output buffer and xterm (see |perlsupport-output|).

1.9.2  CHECK SYNTAX                                 *perlsupport-syntax-check*
-------------------
The script is run as "perl -wc  xxx.pl" with most warnings enabled to check the
syntax.
The Perl script efm_perl.pl (from the VIM standard distribution with a minor
improvement) is needed for checking the syntax of a file with a file name or a
pathname containing blanks.  Due to a weakness in the file name representation
in the Perl output, messages have to be filtered in order to be processed
correctly by the VIM quickfix system.
This script has to be executable under UNIX.

Consider using maps like 
  noremap  <silent> <F7>    :cp<CR>
  noremap  <silent> <F8>    :cn<CR>
in your .vimrc file to jump over the error locations and make navigation
easier (see also file customization.vimrc |perlsupport-custom-files|).
The error list and the error locations in your source buffer will be
synchronized.

1.9.3  COMMAND LINE ARGUMENTS                       *perlsupport-cmdline-args*
-----------------------------
The item 'command line arguments' calls an input dialog which asks for
command line arguments. These arguments are forwarded to the script which
is run by the 'run' item. The arguments are kept until you change them.
The arguments can contain pipes and redirections, e.g.
  " infile.txt | sort -rn > result.txt"
For the first and only the first argument file name expansion will work (use
the Tab-key).

The arguments belong to the current buffer (that is, each buffer can have its
own arguments). The input dialog has a history.

If the buffer gets a new name with "save as" the arguments will now belong to
the buffer with the new name.

1.9.4  PERL COMMAND LINE SWITCHES                  *perlsupport-perl-switches*
---------------------------------
The item 'perl switches' calls an input dialog which asks for command line
switches for the perl interpreter. These arguments are forwarded to the call
of the script which is run by the 'run' item. The switches are kept until you
change them.

The switches belong to the current buffer (that is, each buffer can have its
own switches). The input dialog has a history.

If the buffer gets a new name with "save as" the switches will now belong to
the buffer with the new name.

1.9.5  DEBUG                                           *perlsupport-run-debug*
------------
Start a debugger from the menu item Run->debug, with hotkey \rd or F9. One of
three debuggers can be started. The preference can be set with the variable
g:Perl_Debugger (possible values: 'perl', 'ptkdb', 'ddd' ). The default is
'perl').

(1) perl
The script will be run as 'perl -d my-script.pl my-arguments' in an xterm.

(2) ptkdb
The debugger ptkdb will be started as an independent process. ptkdb is a Perl
debugger using a Tk GUI. The module Devel::ptkdb and the Tk tool kit have to be
installed (see |perlsupport-dependencies|).

(3) ddd
The data display debugger ddd is a graphical front end for GDB (see
|perlsupport-dependencies|). It will be started as an independent process.
The debugger ddd is not available under MS-Windows.

The debugger starts in an separate xterm or is a separate GUI-application
(e.g. ddd). 

Command line arguments (see |perlsupport-cmdline-args|) will be passed on to
the debugger.

Debugging without GUI
---------------------
The hotkey \rd or F9 can be used to start the debugger inside the vim window.
The script will be run with 'perl -d my-script.pl my-arguments'.

1.9.6  READ PERLDOC                                  *perlsupport-perldoc*
-------------------
If a (key-)word is under the cursor the item 'read perldoc' tries to look up
the Perl documentation for this word using perldoc.  If a whitespace is under
the cursor the user will be asked for a keyword.  Search order:
 1. modules     *-<-+
 2. functions   |   |
 3. FAQs        +->-+
This sequence is organized as a ring. If you search for the same item in the
module description (if any) again the plugin tries to look up a function
description, then a FAQ and then the module description again.

On a UNIX platform errors produced by perldoc will be suppressed (a few
module descriptions have POD errors!). 


1.9.7  GENERATE PERL MODULE LIST          *perlsupport-module-list-generation*
--------------------------------
The item 'Run -> generate Perl module list' generates a text file (default:
$HOME/.vim/perl-support/modules/perl-modules.list ) which contains one line
for each Perl module installed on your machine:

    ...
  Fcntl                        (1.05)    - load the C Fcntl.h defines
  File::Basename               (2.72)    - split a pathname into pieces
  File::CheckTree              (4.3)     - run many filetest checks on a tree
  File::Compare                (1.1003)  - Compare files or filehandles
  File::Copy                   (2.07)    - Copy files or filehandles
    ...

The module list is generated by the Perl script  
$HOME/.vim/perl-support/modules/pmdesc3.pl (based on pmdesc2 by Aristotle, see
|perlsupport-credits| ).  This script has to be executable under UNIX. The
generation may take a while.  pmdesc3.pl has a POD included; see file
doc/pmdesc3.text .

1.9.8  SHOW INSTALLED PERL MODULES                  *perlsupport-module-list*
----------------------------------
The item 'Run -> show installed Perl modules' loads the module list in a new
window.  The full documentation for that module can be opened in a perldoc
help window using the hot keys <Shift-F1>, \h or \rp .
Looking up help with Shift-F1 works also in the perldoc help window.
Vim (without GUI): only \h and \rp are working.

1.9.9  RUN PERLTIDY                                     *perlsupport-perltidy*
-------------------
The buffer can be formatted with perltidy. If nothing is marked the whole
buffer will be formatted. If a region is marked only this region will be
formatted.
Perltidy has a lot of options. It is recommended to use a .perltidyrc
initialization file to define the preferred style (see 'man 1 perltidy').
See also |perlsupport-troubleshooting|.

1.9.10  RUN SMALLPROF                                    *perlsupport-profile*
---------------------
Profile the script in the current buffer using the profiler  Devel::SmallProf
(see |perlsupport-dependencies|). The results will go to the file
smallprof.out in the current directory. This file will be opened
automatically.  Devel::SmallProf (version 2.00_03) is controlled by 4
variables (default values shown here):

 $DB::drop_zeros  = 0;           # Do not show lines which were never called: 1
 $DB::grep_format = 0;           # Output on a format similar to grep : 1
 $DB::profile     = 1;           # Turn off profiling for a time: 0
 %DB::packages    = ('main'=>1); # Only profile code in a certain package.

These variables can be put in a file called .smallprof in the current
directory. See the module documentation for more information.

Command line arguments (see |perlsupport-cmdline-args|) will be passed on to
the profiler.

1.9.11 RUN PERLCRITIC                                 *perlsupport-perlcritic*
---------------------
"perlcritic" is a Perl source code analyzer (by Jeffrey Ryan Thalhammer;
search CPAN for the latest version; see also |perlsupport-dependencies|).
This excellent tool is the executable front-end to the Perl::Critic engine,
which attempts to identify awkward, hard to read, error-prone, or
unconventional constructs in your code.  Most of the rules are based on Damian
Conway's book Perl Best Practices (PBP).  When run from the menu the current
buffer will be saved and run through perlcritic. The reported violations will
be displayed in a separate quickfix error window.

Two perlcritic comand line options can be set by this plugin:
 -severity N  :  Directs perlcritic to only report violations of Policies with
                 a severity greater than N.
 -vebose   N  :  Sets the verbosity level for reporting violations.

SEVERITY
--------
Perlcritic (version 1.02) has 5 severity levels (perlcritic default level is
5).  This plugin sets the default level to 3.  This can be changed by setting
the variable g:Perl_PerlcriticSeverity in .vimrc to another value (1-5):

  let g:Perl_PerlcriticSeverity = 1

I addition there is an Ex command to do that, e.g.:

  :CriticSeverity 2

The severity names can also be used (gentle, stern, harsh, cruel, brutal).

VERBOSITY
---------
Perlcritic (version 1.02) has 11 verbosity levels (default level is 4). Some
levels are equal except for the filename and are therefore treated equal
because the quickfix error system used by this plugin needs a filename. 
The message format will not be exactly the same as from a command line
execution of perlcritic but the information displayed will be the same for the
different verbosity levels. The reason also lies in some peculiarities of the
quickfix error system used by Vim.

See the perlcritic documentation for details.

Verbosity 3 is the default.  This can be changed by setting the variable
g:Perl_PerlcriticVerbosity in .vimrc to another value (1-11):

  let g:Perl_PerlcriticVerbosity = 9

I addition there is an Ex command to do that, e.g.:

  :CriticVerbosity 9

OPTIONS
-------
There is another Ex command to set further options, e.g.

  :CriticOptions  -top 10

These options are put behind the severity and verbosity option. The actual
values are shown in the plugin settings (|perlsupport-settings|). These
options can be reset with 
  :CriticOptions

Settings done with CriticOptions override the settings by
g:Perl_PerlcriticOptions (if any).

The default configuration file for perlcritic is '.perlcriticrc'. perlcritic
will look for this file in the current directory first, and then in your home
directory.  See the manual for more information ('man perlcritic' or
'perlcritic -man') especially how to influence the policies.

For easier navigation in the error list see tip under
|perlsupport-syntax-check|.

1.9.12 SAVE BUFFER WITH TIMESTAMP                      *perlsupport-timestamp*
---------------------------------
Save the current buffer into a new file. The filename gets a trailing
timestamp.  The format is YYYYMMDD-HHMMSS.
This feature can be used to comfortably save different profiling results
but it will work with any named buffer.
If you do a lot of profiling you want to add timestamps automatically. To
enable this feature put the following line into .vimrc :

  let g:Perl_ProfilerTimestamp     = "yes"   

The default value is "no".

1.9.13 HARDCOPY                                         *perlsupport-hardcopy*
---------------
Generates a PostScript file from the whole buffer or from a marked region.
On a MS-Windows system a printer dialog is displayed.

The print header contains date and time for the current locale. The definition
used is
 
  let s:Perl_Printheader = "%<%f%h%m%<  %=%{strftime('%x %X')}     Page %N"

The current locale can be overwritten by changing the language, e.g. 

  :language C

or by setting a global variable in the file .vimrc , e.g. :

  let g:Perl_Printheader = "%<%f%h%m%<  %=%{strftime('%x %X')}     SEITE %N"

See :h printheader and :h strftime()  for more details. 

1.9.14 SETTINGS AND HOTKEYS                             *perlsupport-settings*
---------------------------
This menu item shows actual settings for the plugin. Some of them can change
during a session (e.g. current output destination or perlcritic verbosity).

1.9.15 XTERM SIZE                                          *perlsupport-xterm*
-----------------
The size of the xterm used for debugging (|perlsupport-run-debug|) or for
running the script (below) can be set by this menu item. The default is 80
columns with 24 lines.
This feature is not available under MS-Windows.

1.9.16 CHANGE OUTPUT DESTINATION                          *perlsupport-output*
--------------------------------
Running a Perl script can be done in three ways:
(1) The script can be run from the command line as usual.
(2) The output can be directed into a window with name "Perl-Output".
    The buffer and its content will disappear when the window is closed and
    reused otherwise. If this window remains open it will be used for the next
    runs. If the script doesn't produce shell output the output window will 
    not be opened (but you will see a message).
    There is no file behind the window Perl-Output but the content can be 
    saved with a 'save as'.
(3) The script can be run in an xterm.

The output method can be chosen with the menu item 'Run->output: ...'.
This menu has three states:

  output: VIM->buffer->xterm
  output: BUFFER->xterm->vim
  output: XTERM->vim->buffer

The first (uppercase) item shows the current method.  The default is 'vim'.
This can be changed by setting the variable g:Perl_OutputGvim to another value.
Possible values are 'vim', 'buffer' and 'xterm' .

Vim (non-GUI) : The output destination can be toggled between (1) and (2)
                using the hotkey \ro .  

The xterm defaults can be set in .vimrc by the variable g:Perl_XtermDefaults .
The default is "-fa courier -fs 12 -geometry 80x24" :
  font name     : -fa courier
  font size     : -fs 12
  terminal size : -geometry 80x24
See 'xterm -help' for more options. Xterms are not available under MS-Windows.

------------------------------------------------------------------------------
1.10  'help'                                                *perlsupport-help*
------------------------------------------------------------------------------

The root menu item 'help' shows this plugin help in a help window.  The help
tags must have been generated with
  :helptags ~/.vim/doc

==============================================================================
2.  USAGE WITHOUT GUI  (Vim)                            *perlsupport-mappings*
==============================================================================

The frequently used constructs can be inserted with key mappings.  These
mappings are also described in the document perl-hot-keys.pdf (reference
card).
The mappings can be suppressed with the following line in the file .vimrc :
  let g:Perl_NoKeyMappings = 1

All mappings (except \lps and \ups) are filetype specific: they are only
defined for buffers with filetype 'perl' to minimize conflicts with mappings
from other plugins.
The insert mode mappings start with ` (backtick).  

Legend:  (i) insert mode, (n) normal mode, (v) visual mode

  -- Load / Unload Perl Support ------------

  \lps    load perl support                       (n)
  \ups    unload perl support                     (n)

  -- Comments ------------------------------

  \cl      line end comment                  (n,v,i)
  \cj      adjust line end comments          (n,v  )
  \cs      set end comment col.              (n    )
  \cfr     frame comment                     (n   i)
  \cfu     function description              (n   i)
  \cm      method description                (n   i)
  \ch      file header (*.pl)                (n    )
  \ce      file header (*.pm)                (n    )
  \ca      file header (*.t)                 (n    )
  \ckb     keyword comment BUG               (n   i)
  \ckt     keyword comment TODO              (n   i)
  \ckr     keyword comment TRICKY            (n   i)
  \ckw     keyword comment WARNING           (n   i)
  \cko     keyword comment WORKAROUND        (n   i)
  \ckn     keyword comment new keyword       (n   i)
  \cc      toggle comment                    (n,v  )
  \cb      code block to comment             (n,v  )
  \cn      uncomment code block              (n,v  )
  \cd      date                              (n   i)
  \ct      date & time                       (n   i)
  \cv      vim modeline                      (n   i)

  -- Statements ----------------------------

  \sd      do { } while                      (n,v,i)
  \sf      for { }                           (n,v,i)
  \so      foreach { }                       (n,v,i)
  \si      if { }                            (n,v,i)
  \sie     elsif { }                         (n,v,i)
  \se      if { } else { }                   (n,v,i)
  \su      unless { }                        (n,v,i)
  \sn      unless { } else { }               (n,v,i)
  \st      until { }                         (n,v,i)
  \sw      while { }                         (n,v,i)
  \s{      { }                               (n,v,i)

  \nr      read code snippet                 (n)
  \nw      write code snippet                (n,v)
  \ne      read code snippet                 (n)

  -- Idioms --------------------------------

  \$       my $;                (*)          (n   i)
  \$=      my $ = ;             (*)          (n   i)
  \$$      my ( $, $ );         (*)          (n   i)
  \@       my @;                (*)          (n   i)
  \@=      my @ = (,,);         (*)          (n   i)
  \%       my %;                (*)          (n   i)
  \%=      my % = (=>,=>,);     (*)          (n   i)
  \ir      my $regex_ = q//;                 (n   i)
  \im      $ =~ m//                          (n   i)
  \is      $ =~ s///                         (n   i)
  \it      $ =~ tr///                        (n   i)
  \isu     subroutine                        (n,v,i)
  \ip      print "...\n";                    (n   i)
  \ii      open input file                   (n,v,i)
  \io      open output file                  (n,v,i)
  \ipi     open pipe                         (n,v,i)

  -- Regular Expressions -------------------

  \xr      pick up Regex                     (n,v)
  \xs      pick up string                    (n,v)
  \xf      pick up flags                     (n,v)
  \xm      match                             (n)
  \xe      explain Regex                     (n,v)

  -- POSIX Character Classes ---------------

  \pa      [:alnum:]                         (n   i)
  \ph      [:alpha:]                         (n   i)
  \pi      [:ascii:]                         (n   i)
  \pb      [:blank:]                         (n   i)
  \pc      [:cntrl:]                         (n   i)
  \pd      [:digit:]                         (n   i)
  \pg      [:graph:]                         (n   i)
  \pl      [:lower:]                         (n   i)
  \pp      [:print:]                         (n   i)
  \pn      [:punct:]                         (n   i)
  \ps      [:space:]                         (n   i)
  \pu      [:upper:]                         (n   i)
  \pw      [:word:]                          (n   i)
  \px      [:xdigit:]                        (n   i)

  -- Run -----------------------------------

  \rr     update file, run script         (n)   see |perlsupport-run-script|
  \rs     update file, check syntax       (n)   see |perlsupport-syntax-check|
  \ra     set command line argument       (n)   see |perlsupport-cmdline-args|
  \rw     set Perl command line switches  (n)   see |perlsupport-perl-switches|
  \rd     start debugger                  (n)   see |perlsupport-run-debug|
  \re     make script executable (**)     (n)   
  \rp     read perldoc                    (n)   see |perlsupport-perldoc|  
  \ri     show installed Perl modules     (n)   see |perlsupport-module-list|  
  \rg     generation Perl module list     (n)   see |perlsupport-module-list-generation|
  \ry     run perltidy                    (n,v) see |perlsupport-perltidy| 
  \rm     run SmallProf                   (n)   see |perlsupport-profile|  
  \rc     run perlcritic                  (n)   see |perlsupport-perlcritic|  
  \rt     save buffer with timestamp      (n)   see |perlsupport-timestamp|
  \rh     hardcopy buffer to FILENAME.ps  (n,v) see |perlsupport-hardcopy| 
  \rk     settings and hotkeys            (n)   
  \rx     set xterm size (**)             (n)   see |perlsupport-xterm|
  \ro     change output destination       (n)   see |perlsupport-output|

  -- Help ----------------------------------

  \h      read perldoc                    (n)   see |perlsupport-perldoc|

(*)  These key mappings start like Perl references. They are therefore not
     available in insert mode for non-empty lines.
(**) Linux/UNIX only

File perl-hot-keys.pdf contains a reference card for these key mappings.
Multi-line inserts and code snippets will be indented after insertion.

The hot-keys are defined in the file type plugin perl.vim (part of this
perl-support plugin package).

The mappings can also be used with gVim.

Changing the default map leader '\'
-----------------------------------
The map leader can be changed by the user by setting a global variable in the
file .vimrc 

 let g:BASH_MapLeader  = ','

The map leader is now a comma. The 'line end comment' command is now defined
as ',cl'. This setting will be used as a so called local leader and influences
only files with filetype 'sh'.

Resolving conflicts 
-------------------
Sometimes the map leader "\" may conflict with Perl constructs e.g. when 
typing an array reference: \@arrayname . There are two solutions.

(1) Typing speed matters. Type \ and wait some hundred milliseconds. The
following character will no longer be recognized as belonging to the backslash
as map leader.

(2) Change the map leader to another character, e.g. to the backtick with
      :let mapleader="`"
You can make this change permanent by adding this line to the file .vimrc .
CAVEAT: This setting is global and influences all filetypes.

==============================================================================
3.  FUNCTION KEYS                                  *perlsupport-function-keys*
==============================================================================

The following function keys are defined in normal, visual and insert mode:

   Shift-F1   read perldoc  (for the word under the cursor)
         F9   start a debugger
     Alt-F9   run syntax check
    Ctrl-F9   run script
   Shift-F9   set command line arguments (buffer related)

These function keys are defined in the file type plugin ~/.vim/ftplugin/perl.vim .

Note for xterm users (Vim without GUI): The function key combinations
Shift-Fx, Alt-Fx and Ctrl-Fx do not work. F9 is also not working to prevent
unintentional use.  Use mappings instead (|perlsupport-mappings|).

==============================================================================
4.  CUSTOMIZATION                                  *perlsupport-customization*
==============================================================================

------------------------------------------------------------------------------
4.1  FILES                                          *perlsupport-custom-files*
------------------------------------------------------------------------------

README.perlsupport        This file.

doc/perlsupport.txt               The help file for the local online help. 
                          
ftplugin/perl.vim         A filetype plugin. Define hotkeys, create a local 
                          dictionary for each Perl file.

plugin/perl-support.vim   The Perl plugin for Vim/gVim.

perl-support/codesnippets-perl/*  Some Perl code snippets as a starting point.

perl-support/modules/             Directory for the list of installed Perl modules

perl-support/scripts/efm_perl.pl  Perl script; Reformats the error messages of the Perl interpreter
perl-support/scripts/pmdesc3.pl   Perl script; generates a list of all installed Perl modules
perl-support/scripts/wrapper.sh   The wrapper script for the use of an xterm.

perl-support/templates/perl-file-header           -+-  Perl template files 
perl-support/templates/perl-frame                  |   (see perlsupport.txt)
perl-support/templates/perl-function-description   |
perl-support/templates/perl-module-header          |
perl-support/templates/perl-pod                    |
perl-support/templates/perl-test-header           -+

perl-support/wordlists/perl.list  A file used as dictionary for automatic word completion.
                                  This file is referenced in the file customization.vimrc.

-----------------------   -------------------------------------------------------------
-----------------------   The following files and extensions are for convenience only.
                          perl-support.vim will work without them.
                          -------------------------------------------------------------

perl-support/rc/customization.ctags       Additional settings I use in  .ctags to enable
                                          navigation through POD with the plugin taglist.vim.

perl-support/rc/customization.gvimrc      Additional settings I use in  .gvimrc:
                                          hot keys, mouse settings, ...
                                          The file is commented. Append it to your .gvimrc 
                                          if you like.

perl-support/rc/customization.perltidyrc  Additional settings I use in  .perltidyrc to 
                                          customize perltidy.

perl-support/rc/customization.smallprof   Additional settings I use to control the profiler 
                                          Devel::SmallProf

perl-support/rc/customization.vimrc       Additional settings I use in  .vimrc:  incremental search,
                                          tabstop, hot keys, font, use of dictionaries, ...
                                          The file is commented. Append it to your .vimrc if you like.

perl-support/doc/perl-hot-keys.pdf        Reference card for the key mappings. 
                                          The mappings can also be used with the non-GUI Vim, 
                                          where the menus are not available.
perl-support/doc/pmdesc3.text             The man page for pmdesc3.
perl-support/doc/ChangeLog                The change log.

------------------------------------------------------------------------------
4.2  GLOBAL VARIABLES                           *perlsupport-custom-variables*
------------------------------------------------------------------------------

Several global variables are checked by the script to customize it:

------------------------------------------------------------------------------
global variable                default value               tag (see below)
------------------------------------------------------------------------------
g:Perl_AuthorName              ""                         *|AUTHOR|*
g:Perl_AuthorRef               ""                         *|AUTHORREF|*
g:Perl_Company                 ""                         *|COMPANY|*
g:Perl_CopyrightHolder         ""                         *|COPYRIGHTHOLDER|*
g:Perl_Email                   ""                         *|EMAIL|*
g:Perl_Project                 ""                         *|PROJECT|*

g:Perl_Template_Directory      root_dir.'perl-support/templates/'
g:Perl_Template_File           'perl-file-header'
g:Perl_Template_Module         'perl-module-header'
g:Perl_Template_Test           'perl-test-header'
g:Perl_Template_Pod            'perl-pod'
g:Perl_Template_Frame          'perl-frame'
g:Perl_Template_Function       'perl-function-description'

g:Perl_CodeSnippets            root_dir.'perl-support/codesnippets/'
g:Perl_LoadMenus               'yes'
g:Perl_Dictionary_File         ''
g:Perl_Root                    '&Perl.'
g:Perl_MenuHeader              'yes'

g:Perl_PerlModuleList          root_dir.'perl-support/modules/perl-modules.list'
g:Perl_PerlModuleListGenerator root_dir.'perl-support/scripts/pmdesc3.pl'
g:Perl_OutputGvim              "vim"
g:Perl_XtermDefaults           "-fa courier -fs 12 -geometry 80x24"
g:Perl_Debugger                "perl"
g:Perl_ProfilerTimestamp       "no"
g:Perl_LineEndCommColDefault   49
g:Perl_BraceOnNewLine          "no"
g:Perl_PodcheckerWarnings      "yes"
g:Perl_Printheader             "%<%f%h%m%<  %=%{strftime('%x %X')}     Page %N"
g:Perl_PerlcriticSeverity      5
g:Perl_PerlcriticVerbosity     5
g:Perl_PerlcriticOptions       ""
g:Perl_PerlRegexSubstitution   '$+'

g:Perl_NoKeyMappings           - undefined -
g:Perl_MapLeader               '\'

The variable root_dir will automatically be set to one of the following values:
  $HOME.'/.vim/'        for Linux/Unix
  $VIM.'/vimfiles/'     for MS-Windows

------------------------------------------------------------------------------

1. group: Defines the text which will be inserted for the tags when a template
          is read in (see also TEMPLATE FILES AND TAGS below).

          g:Perl_AuthorName      : author name
          g:Perl_AuthorRef       : author reference (e.g. acronym)
          g:Perl_Email           : email address
          g:Perl_Company         : name of the company / institution
          g:Perl_Project         : project
          g:Perl_CopyrightHolder : the copyright holder

2. group: Sets the template directory and the names of the template files (see below).

3. group: g:Perl_CodeSnippets    : The name of the code snippet directory (see below).
          g:Perl_LoadMenus       : Load menus and mappings ("yes", "no") at startup.
          g:Perl_Dictionary_File : Path and filename of the Perl word list used for
                                   dictionary completion (see below).
          g:Perl_Root            : The name of the root menu item of this plugin
                                   (see below).
          g:Perl_MenuHeader      : Switch submenu titles on/off.

4. group: g:Perl_PerlModuleList          : The name of the Perl module list (text file,
                                           see below).
          g:Perl_PerlModuleListGenerator : The command line which starts the
                                           module list generation.
          g:Perl_OutputGvim              : when script is running output goes to the vim
                                           command line ("vim"), to a buffer ("buffer")
                                           or to an xterm ("xterm").
          g:Perl_XtermDefaults           : the xterm defaults
          g:Perl_Debugger                : the debugger called by F9 (perl, ptkdb, ddd).
          g:Perl_ProfilerTimestamp       : add time stamp to the profiler buffer name
          g:Perl_LineEndCommColDefault   : default starting column for line end comments
          g:Perl_BraceOnNewLine          : opening brace (not) on a new line
          g:Perl_PodcheckerWarnings      : podchecker warnings on/off
          g:Perl_Printheader             : hardcopy header format 
          g:Perl_PerlcriticSeverity      : perlcritic severity
          g:Perl_PerlcriticVerbosity     : perlcritic verbosity
          g:Perl_PerlcriticOptions       : additional perlcritic options
          g:Perl_NoKeyMappings           : suppress command mappings (|perlsupport-mappings|)
          g:Perl_MapLeader               : map leader for hotkeys (|perlsupport-mappings|)
          g:Perl_PerlRegexSubstitution   : regex control character substitutions

To override the defaults add appropriate assignments to .vimrc .
Set at least some personal details into .vimrc by overriding some defaults.
Here the minimal personalization (my settings as an example, of course):

      let g:Perl_AuthorName      = 'Dr.-Ing. Fritz Mehner'
      let g:Perl_AuthorRef       = 'Mn'
      let g:Perl_Email           = 'mehner@fh-swf.de'
      let g:Perl_Company         = 'FH Südwestfalen, Iserlohn'


------------------------------------------------------------------------------
4.3  THE ROOT MENU                                   *perlsupport-custom-root*
------------------------------------------------------------------------------

The variable g:Perl_Root, if set in .vimrc or in .gvimrc, gives the name of
the single gVim root menu item in which the Perl submenus are contained. The
default is
                  '&Perl.'

Please note the terminating dot. A single root menu item is appropriate if the
screen is limited or several plugins are in use.

If set to '' (empty string) with

  let g:Perl_Root = ''

this single root menu item will not appear.  Now all submenus are put into the
gVim root menu. Nice for a Perl-only-programmer and Perl courses with wide
screens.

If you want to set the plugin root menu as a submenu into another menu, e.g.
your own with the name 'Plugin', this is done by the following line in '.vimrc'

  let g:Perl_Root = '&Plugin.&Perl.'

The appearance of the root menu item can also be controlled by the global
variable g:Perl_LoadMenus. The line 

  let g:Perl_LoadMenus    = 'no'

prevents the root menu item from appearing when the editor starts. You can
switch it on (and off again) from the tools menu. The default for this
variable is 'yes'.


------------------------------------------------------------------------------
4.4  NAVIGATE THROUGH PODs                       *perlsupport-custom-navigate*
------------------------------------------------------------------------------

The plugin taglist.vim (Author: Yegappan Lakshmanan) is a source code browser
plugin for Vim and provides an overview of the structure of source code files
and allows you to efficiently browse through source code files for different
programming languages. It is based on  ctags (Exuberant Ctags, Darren Hiebert,
http://ctags.sourceforge.net).
The file rc/customization.ctags is an extension for the configuration file of
ctags.  If appended to $HOME/.ctags (the initialization file for ctags)
taglist can show the structure of the included POD as an table of content.

The taglist navigation window for the module Eliza.pm starts like this:

  Eliza.pm (/home/mehner)
    subroutines
      Version
      new
      _initialize
      AUTOLOAD
      command_interface
      preprocess
      postprocess
      _testquit
      _debug_memory
      transform
      parse_script_data

    POD
      NAME
      SYNOPSIS
      DESCRIPTION
      INSTALLATION
      USAGE
      MAIN DATA MEMBERS
      . %decomplist
      . %reasmblist
      . %reasmblist_for_memory
          . . .

Now you can navigate through the embedded POD with a mouse click on these
entries. To enable this feature

1) append rc/customization.ctags to $HOME/.ctags (or create this file)

2) add the following lines to $HOME/.vimrc :

  "
  "-----------------------------------------------------------------------------
  " taglist.vim : toggle the taglist window
  " taglist.vim : define the title texts for Perl
  "-----------------------------------------------------------------------------
   noremap <silent> <F11>       :Tlist<CR>
  inoremap <silent> <F11>  <C-C>:Tlist<CR>

  let tlist_perl_settings  = 'perl;c:constants;l:labels;p:package;s:subroutines;d:POD'

3) restart vim/gvim

The two maps will toggle the taglist window (hotkey F11) in all editing modes.
The assignment defines the headings for the Perl sections in the taglist window.

IMPORTANT : The POD contents will not be displayed if the POD comes after an
__END__ token. Ctags (current version 5.6) does not parse beyond this token.
You may therefore want not to use __END__ in your own modules.

------------------------------------------------------------------------------
4.5  Tabulator width                                  *perlsupport-custom-tab*
------------------------------------------------------------------------------

The Perl Style Guide recommends a tabulator setting of 4. You can force this
setting for all files with file type 'perl' by uncommenting the two lines

  "setlocal tabstop=4
  "setlocal shiftwidth=4

in the file type plugin '~/.vim/ftplugin/perl.vim' . 

------------------------------------------------------------------------------
4.6  Syntax based folding                                *perlsupport-folding*
------------------------------------------------------------------------------

Syntax based folding can be enabled by adding the following lines to the file
'~/.vim/syntax/perl.vim':

  let perl_fold=1
  let perl_fold_blocks=1
  "
  " initially all folds open
  set foldlevel=999

You may have to create this file first. See |folding| for more information.

------------------------------------------------------------------------------
4.7  System-wide installation (Unix/Linux only)      *perlsupport-system-wide*
------------------------------------------------------------------------------

A system-wide installation (one installation for all users) is done as
follows.

As *** SUPERUSER *** :

(1) Find the Vim installation directory.
The Vim ex command ':echo $VIM' gives '/usr/local/share/vim' or something like
that. Beyond this directory you will find the Vim installation,  e.g. in
'/usr/local/share/vim/vim71' if Vim version 7.1 has been installed.

(2) Create a new subdirectory 'vimfiles', e.g. '/usr/local/share/vim/vimfiles'.

(3) Install Perl Support
Copy the archive perl-support.zip to this new directory and unpack it:
  unzip perl-support.zip

(4) Generate the help tags:
  :helptags $VIM/vimfiles/doc


As *** USER *** :

Create your private snippet directory:

  mkdir --parents  ~/.vim/perl-support/codesnippets 

You may want to copy the snippets comming with this plugin (in
$VIM/vimfiles/perl-support/codesnippets) into the new directory or to set a
link to the global directory.

==============================================================================
5.  TEMPLATE FILES AND TAGS                            *perlsupport-tempfiles*
==============================================================================

------------------------------------------------------------------------------
5.1  TEMPLATE FILES 
------------------------------------------------------------------------------

Four menu entries generate block comments:

    Perl -> Comments -> Frame Comm.
    Perl -> Comments -> Function Descr.
    Perl -> Comments -> File Header (.pl)
    Perl -> Comments -> File Header (.pm)

The comments which will be inserted by these menu entries are read from
template files:

------------------------------------------------------------------------------
MENU ITEM               FILE                          GLOBAL VARIABLE
------------------------------------------------------------------------------
Frame Comment           perl-frame                    g:Perl_Template_Frame
Function Description    perl-function-description     g:Perl_Template_Function
File Header (.pl)       perl-file-header              g:Perl_Template_File
File Header (.pm)       perl-module-header            g:Perl_Template_Module
File Header (.t)        perl-test-header              g:Perl_Template_Test
                        perl-pod                      g:Perl_Template_Pod
------------------------------------------------------------------------------

The template files can be written or changed by the user to fulfill special
requirements (layout for a project or work group already exists, file headers /
blocks have to be prepared for a documentation tool, ... ).  They can hold not
only comments but a complete file skeleton if this is necessary.  So you may
want to lay out your own templates.

The file 'perl-pod' contains a file header and a skeleton for a pod file.
This skeleton will be automatically included when a new pod file is opened.

The templates belonging to this plugin package are suggestions. You may want
to create your own templates.

------------------------------------------------------------------------------
5.2  TAGS                                                   *perlsupport-tags*
------------------------------------------------------------------------------

The comments in these files do not have to be personalized but they can.
The text can contain the following tags which are replaced by the appropriate
information when the file is read in:

   *|AUTHOR|*
   *|AUTHORREF|*
   *|COMPANY|*
   *|COPYRIGHTHOLDER|*
   *|EMAIL|*
   *|PROJECT|*

   *|DATE|*
   *|FILENAME|*
   *|TIME|*
   *|YEAR|*

   *|CURSOR|*

Each tag can occur more than once. The tag |CURSOR| may appear only once.
The tag |CURSOR| will be the cursor position after the block is read in.
There is no need to use any of these tags, some or all can be missing.

The template files can actually be links pointing to existing templates.

------------------------------------------------------------------------------
5.3  Perl::Tags                                         *perlsupport-perltags*
------------------------------------------------------------------------------

The use of the module Perl::Tags (version 0.23; see CPAN) is encouraged.
In order to use this feature you need a Vim binary with Perl interface
compiled in (see below) and Perl::Tags must be installed,  of course.

Usage. If the cursor is on the module name in a perl 'use' ore 'require'
statement like

  use Graphics::GnuplotIF qw(GnuplotIF);

a CTRL-] let you jump into the file GnuplotIF.pm.  An easy way back is with
the CTRL-T command.  See also the module documentation on how to use
Perl::Tags.

The script perl-support/scripts/perltags.vim (which is drawn from the
Perl::Tags documentation) will be loaded from the filetype plugin
'ftplugin/perl.vim'. The tag files will be created in '/tmp'. MS-Windows user
have possibly to create this directory.


Compiling VIM with Perl interface
---------------------------------
To use the module Perl::Tags Vim has to be compiled with Perl interface (not
to be confused with this plugin; see also |perl|). To check this display the
version information with
  :version
and look for the features section. A '+perl' says that your binary was
compiled with Perl interface. 

Compile Vim from the sources:

(1) Get the tarball from http://vim.sourceforge.net/ and unpack it.
(2) Configure with

      ./configure --enable-perlinterp --enable-gui=gtk2

    for Perl and your favorite GUI.
(3) Make the binary the traditional way:
      make
      make test
      make install  (you must be root)
    You may want to install patches before the first make.

Depending on your GUI you will probably need some additional graphics
libraries.

==============================================================================
6.  PERL DICTIONARY                                   *perlsupport-dictionary*
==============================================================================

The file  perl.list  contains words used as dictionary for automatic word
completion.  This feature is enabled by default. The default word list is

  $HOME/.vim/perl-support/wordlists/perl.list

If you want to use an additional list MyPerl.List put the following line into
 .vimrc :

  let g:Perl_Dictionary_File   =  "$HOME/.vim/perl-support/wordlists/perl.list,".
                              \   "$HOME/any_of_my_directories/MyPerl.List"

The right side is a comma separated list of files. Note the point at the end
of the first line (string concatenation) and the backslash in front of the
second line (continuation line).
You can use Vim's dictionary feature CTRL-X, CTRL-K (and CTRL-P, CTRL-N).


==============================================================================
7.  OPTIONAL DEPENDENCIES                           *perlsupport-dependencies*
==============================================================================

There are several optional dependencies.

------------------------------------------------------------------------------
7.1 Standard Perl modules
------------------------------------------------------------------------------

These modules should come with your Perl distribution:

  perldoc    - Look up Perl documentation in Pod format
  pod2html   - convert .pod files to .html files
  pod2man    - Convert POD data to formatted *roff input
  pod2text   - Convert POD data to formatted ASCII text
  podchecker - check the syntax of POD format documentation files

------------------------------------------------------------------------------
7.2 Non-standard Perl modules
------------------------------------------------------------------------------

The following modules have to be installed by the user/administrator in order
to use them.

  Devel::SmallProf     - per-line Perl profiler
  Devel::ptkdb         - Perl debugger using a Tk GUI
  Perl::Critic         - Critique Perl source code for best-practices
  Perl::Tags           - Generate Ctags style tags for Perl source code 
                         (see |perlsupport-perltags|)
  Perl::Tidy           - Parses and beautifies perl source
  YAPE::Regex::Explain - regular expression analyzer

This is done in one of two way:

(1) Download the tarball from CPAN (http://www.cpan.org/) or one of its
mirrors, go to the new directory, read the files README and INSTALL, and
follow the instructions. You have to resolve the dependencies yourself
by first installing them.

(2) Install the cpan shell (module CPAN) and install modules via network.
The dependencies are resolved automatically. Recommended.

------------------------------------------------------------------------------
7.3 Other applications
------------------------------------------------------------------------------

  ddd - The Data Display Debugger (graphical front-end for GDB)

The homepage of this project is http://www.gnu.org/software/ddd/.

==============================================================================
8.  Compiling Vim                                    *perlsupport-compile-vim*
==============================================================================

You may want to compile Vim yourself because the 'perl' feature is missing.
First, there are two ways to check this:
(1) Type 'version' on the Vim command line and look for 'perl' in the section
"Features includes ... ". 
(2) Type 'echo has("perl")' on the Vim command line. If you get a '0' the
feature is not present.
A ':help :version' will show all possible features to choose from.

You could first look around for a binary distribution with this feature which
was compiled for your platform. Install it and all is done.

COMPILE YOUR OWN VERSION (LINUX/UNIX).
--------------------------------------
(1) Download the sources from 'vim.sourceforge.net' and extract the sources
from the archive (for patches see|perlsupport-compile-vim-patches|).

(2) Inspect the current version again. The section 'Compilation' shows how
this version was built. You can see the libraries used. In order to have your
new version looking like the one you are just using you may have to install
some additional libraries first (the development versions).

(3) Change to the directory containing the source code and type 

  ./configure --enable-perlinterp
  make
  make check

If all was well install the program:

  make install

A './configure --help' prior to these steps will show a lot of options (e.g.
for a local or user installation).

(4) Check if you have to add the target directory for the new installation to
PATH.

(5) Check if the new version starts up when you are in your normal working
environment. You may have to remove the old version to avoid conflicts.

The file 'src/INSTALL' contains more details if needed. 

PATCHES                                      *perlsupport-compile-vim-patches*
-------
Before compiling your own version you may want to include the patches from
ftp.vim.org/pub/vim/patches/. The patch directory contains a file 'README'
which shows how to do that.


==============================================================================
9.  MS-Windows PARTICULARITIES                           *perlsupport-windows*
==============================================================================

The plugins should go into the directory structure below the local
installation directory $HOME/.vim/ for LINUX/UNIX and $VIM/vimfiles/ for
MS-Windows.
The values of the two variables can be found from inside Vim:
   :echo $VIM 
or
   :echo $HOME

Configuration files:

  LINUX/UNIX :   $HOME/.vimrc  and  $HOME/.gvimrc 
  MS-Windows :   $VIM/_vimrc   and  $VIM/_gvimrc


==============================================================================
10.  TROUBLESHOOTING                             *perlsupport-troubleshooting*
==============================================================================

* I do not see any new main menu item.
  - Was the archive extracted into the right directory (see |perlsupport-windows|)?

* How can I see what was loaded?
  - Use ':scriptnames' from the Vim command line. 

* No main menu item.
  - Loading of plugin files must be enabled. If not use
      :filetype plugin on
    This is the minimal content of the file '$HOME/.vimrc'. Create one if there
    is none, or better use customization.vimrc (see |perlsupport-custom-files|).

* Most key mappings do not work.
  - They are defined in a filetype plugin in '$HOME/.vim/ftplugin/'. Use ':filetype'
    to check if filetype plugins are enabled. If not, add the line 
      filetype plugin on
    to the file '.vimrc'.

* Perl script not executable from inside the editor.
  - Script executable from the command line ?
  - Perl installation correct ?
  - PATH variable correct ?
  - Script set executable (file access permission under LINUX/UNIX) ?
  - Script syntax correct ?
  - Necessary modules installed ?

* Some hotkeys (e.g. x-F9) do not work.
  - The hotkeys might be in use by your graphical desktop environment.
    Under KDE Ctrl-F9 is the hotkey which let you switch to the 9. desktop.
    The key settings can usually be redefined or switched off.
    Under KDE, 'Keyboard Shortcuts' may be configured by following:
     K Menu -> Control Center -> Regional & Accessibility -> Keyboard Shortcuts.

* perltidy not running / messing up my file
  Unix/Linux: you have had a proper installation of perltidy, but now it does
  not work or messes up your file.
  The start script '/usr/bin/perltidy' needs the module 'Perl::Tidy.pm'. Most
  likely you have updated Perl and the module can not longer be found. The
  easiest remedy is to reinstall perltidy. Check the installation with the 
  command "perltidy -v" from the command line.
    

==============================================================================
11.  RELEASE NOTES / CHANGELOG                      *perlsupport-release-notes*
==============================================================================

See files 'README.perlsupport' and 'ChangeLog'.

==============================================================================
12.  CREDITS                                             *perlsupport-credits*
==============================================================================

David Fishburn <fishburn@ianywhere.com> for the implementation of the
  single root menu and several suggestions for improving the customization
  and the documentation.

Ryan Hennig <hennig@amazon.com> improved the install script.

Aristotle, http://qs321.pair.com/~monkads/ is the author of the script pmdesc2
  which is the base of the script pmdesc3.pl.

David Fishburn contributed changes for the Windows platform and suggested to
  not let enter snippets and templates the list of alternate files.

The code snippet files pod-template-application.pl and pod-template-module.pl
  are taken from Damian Conway's book "Perl Best Practices".

==============================================================================
vim:tw=78:noet:ts=2:ft=help:norl:
