corwinian / vim-config Goto Github PK

README for perl-support.vim (Version 4.15) / January 23 2012

  *  INSTALLATION
  *  RELEASE NOTES 
  *  FILES
  *  ADDITIONAL TIPS
  *  CREDITS

Perl Support implements a Perl-IDE for Vim/gVim. It has been 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.  There are many additional hints and
options which can improve speed and comfort when writing Perl. Please read the
documentation.
This plugin can be used with Vim version 7.x . Most features should work with
Vim version 6.x.

================================================================================
  INSTALLATION
================================================================================

(1)  LINUX
----------------------------------------------------------------------

The subdirectories in the zip archive  perl-support.zip  mirror the directory
structure which is needed below the local installation directory $HOME/.vim/
(find the value of $HOME with ":echo $HOME" from inside Vim).

(1.0) Save the template files in '$HOME/.vim/perl-support/templates/Templates' if
    you have changed any of them.

(1.1) Copy the zip archive perl-support.zip to $HOME/.vim and run

      unzip perl-support.zip

    If you have already an older version of perl-support and you have modified
    the template files you may want to save your templates first and suppress
    overwriting them with

      unzip perl-support.zip  -x *Templates *.template

(1.2) 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 use the files in $HOME/.vim/perl-support/rc as a starting point.

(1.3) Set at least some personal details in the file 
    '$HOME/.vim/perl-support/templates/Templates' 
    Here is the minimal personalization (my settings as an example):

      |AUTHOR|       = Dr. Fritz Mehner 
      |AUTHORREF|    = fgm
      |EMAIL|        = [email protected]
      |ORGANIZATION| = FH Südwestfalen, Iserlohn
      |COPYRIGHT|    = Copyright (c) |YEAR|, |AUTHOR|

    (Read more about the template system in the plugin documentation)

(1.4) Make the plugin help accessable by typing the following command on the
    Vim command line:

    :helptags $HOME/.vim/doc/
  
(1.5) Consider additional settings in the file '$HOME/.vimrc'.  The files
    customization.vimrc and customization.gvimrc are replacements or extensions
    for your .vimrc and .gvimrc.  You may want to use parts of them. The files
    are documented. 


(2)  WINDOWS
----------------------------------------------------------------------

The subdirectories in the zip archive  perl-support.zip  mirror the directory
structure which is needed below the local installation directory
$HOME/vimfiles/ (find the value of $HOME with ":echo $HOME" from inside Vim).

(2.0) Save the template files in '$HOME/vimfiles/perl-support/templates/Templates'
    if you have changed any of them.

(2.1) Copy the zip archive perl-support.zip to $HOME/vimfiles and run

      unzip perl-support.zip

    If you have already an older version of perl-support and you have modified
    the template files you may want to save your templates first and suppress
    overwriting them with

      unzip perl-support.zip  -x *Templates *.template

(2.2) 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 use the files in $HOME/vimfiles/perl-support/rc as a starting point.

(2.3) Set at least some personal details in the file 
    '$HOME/vimfiles/perl-support/templates/Templates' 
    Here is the minimal personalization (my settings as an example):

      |AUTHOR|       = Dr. Fritz Mehner 
      |AUTHORREF|    = fgm
      |EMAIL|        = [email protected]
      |ORGANIZATION| = FH Südwestfalen, Iserlohn
      |COPYRIGHT|    = Copyright (c) |YEAR|, |AUTHOR|

    (Read more about the template system in the plugin documentation)

(2.4) Make the plugin help accessable by typing the following command on the
    Vim command line:

    :helptags $HOME\vimfiles\doc\
  
(2.5) Consider additional settings in the file '$HOME/_vimrc'.  The files
    customization.vimrc and customization.gvimrc are replacements or extensions
    for your _vimrc and _gvimrc. You may want to use parts of them.  The files
    are documented. 

There are a lot of features and options which can be used and influenced:

  *  use of template files and tags
  *  using and managing personal code snippets
  *  Perl dictionary for keyword completion
  *  the Perl module list
  *  reading Perl documentation with integrated calls to perldoc
  *  removing the root menu
  *  using additional plugins

Look at the perlsupport help with

  :help perlsupport 

               +-----------------------------------------------+
               | +-------------------------------------------+ |
               | |    ** PLEASE READ THE DOCUMENTATION **    | |
               | |    Actions differ for different modes!    | |
               | +-------------------------------------------+ |
               +-----------------------------------------------+

Any problems ? See the TROUBLESHOOTING section at the end of the help file
'doc/perlsupport.txt'.

For a system-wide installation please see the help file 'doc/perlsupport.txt'.

=======================================================================================
  RELEASE NOTES 
=======================================================================================

---------------------------------------------------------------------------------------
  RELEASE NOTES FOR VERSION 4.15
---------------------------------------------------------------------------------------
- Two new plugin tags: LICENCE, ORGANIZATION.
- System-wide installation: minimal Template file for a user will automatically
  be added.
- Hotkeys \lcs, \ucs removed.
- Minor improvements.

---------------------------------------------------------------------------------------
  OLDER RELEASE NOTES : see file 'ChangeLog'
---------------------------------------------------------------------------------------

=======================================================================================
  FILES
=======================================================================================

README.perlsupport                This file.

autoload/perlsupportgui.vim       Menu definitions.
autoload/perlsupportprofiling.vim Profiler support.
autoload/perlsupportregex.vim     Regex analyser code.

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.
ftplugin/pod.vim                  A filetype plugin. Define hotkeys for filetype 'pod'.

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/Templates            Perl main template file
perl-support/templates/comments.template    template file for comments
perl-support/templates/idioms.template      template file for idioms
perl-support/templates/pod.template         template file for pod statements
perl-support/templates/statements.template  template file for statements

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.


=======================================================================================
  ADDITIONAL TIPS
=======================================================================================

(1) You may want to use a central hidden directory for all your backup files (see also
    rc/customization.vimrc ):

    1.1 Add the following line to .vimrc (see also rc/customization.vimrc ):

      set backupdir  =$HOME/.vim.backupdir  
    
    1.2 Create  $HOME/.vim.backupdir  .

    1.3 Add the following line to your shell initialization file  ~/.profile :

      find $HOME/.vim.backupdir/  -name "*" -type f -mtime +60 -exec rm -f {} \;

    When you are logging in all files in the backup directory older then 60
    days (-mtime +60) will be removed (60 days is a suggestion, of course). 
    Be shure to backup in shorter terms !

(2) gVim. Toggle 'insert mode' <--> 'normal mode' with the right mouse button
    (see mapping in file customization.gvimrc).

(3) gVim. Use tear off menus.

(4) Try 'Focus under mouse' as window behavior (No mouse click when the mouse
    pointer is back from the menu entry).

(5) Use Emulate3Buttons "on" (X11) even for a 3-button mouse. Pressing left and
    right button simultaneously without moving your fingers is faster than 
    moving a finger to the middle button (which is often a wheel).


=======================================================================================
  CREDITS
=======================================================================================

David Fishburn <[email protected]> for the implementation of the 
  single root menu and several suggestions for improving the customization
  and the documentation.
  
Ryan Hennig <[email protected]> improved the install script.

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

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

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


=======================================================================================