:: vimsh readme ::

    vimsh is a python script and vim script that allow a user to run
    a shell within a [g]vim buffer.  There are certain requirements and
    some limitations depending on your platform so please read on.  vimsh
    works on both the console and GUI versions of vim so from this point on
    references to vim also include GUI versions of vim.

    *********************************************************************
    NOTE:

        If you like this script and vim users are allowed to vote on new
        features in vim again, PLEASE put in a vote for vi editing in the ex
        command window (not the new command window/buffer).  It's the only
        new feature I would like vim to have.
    *********************************************************************

:: vimsh requirements ::

    requirements summary:

        python enabled vim ( +python )
        operating system that supports pty (unix) -or- popen/pipes (Windows)
	    Tested w/ Python 2.2 and 2.3, 2.4, and 2.5, and 2.6.

        For Debian, the vim-python package is required to use vimsh.

        For Windows, the pywin32 package is required for asynchronous pipes
        support.

            http://sourceforge.net/projects/pywin32/

    requirements in detail:

    vimsh requires a python enabled vim ( +python ), run
    :ver to see if you have +python for your build of vim.

    vimsh also requires that your operating system supports
    either pty ( pseudo ttys ) -or- the popen family of calls.
    Most UNIX variants have support for pty in one form or another
    and most other platforms, for instance Windows, support popen.

    I have tested vimsh on the following configurations, newer releases
    are not always tested with all platforms:

        vim 7.x     / Windows Vista       / python 2.5
        vim 7.x     / Ubuntu Linux        / python 2.5
        vim 7.x     / Mac OS X            / python 2.5
        vim 6.0-6.4 / Gentoo Linux        / python 2.3.3, 2.4.2
        vim 6.0-6.2 / Slackware Linux 8.0 / python 2.2b2, 2.2.3, 2.3.X
        vim 6.0-6.2 / WinNT 4.0           / Activestate Python 2.2
        vim 6.0-6.2 / Win2K               / Standard Python 2.2
        vim 6.0-6.2 / WinXP               / Standard Python 2.2
        vim 6.0-6.2 / FreeBSD 4.6-4.9     / python 2.2.X, 2.3.X

    The pty library is 'unsupported' by python on some platforms
    but I have received reports of success on these platforms
    in addition to the ones I have tested on:

    QNX
    Solaris( waiting for confirmation of fix )

:: running vimsh ::

    You can run vimsh by sourcing the file vimsh.vim on the ex 
    command line like this assuming you are in the directory that
    vimsh.vim is located:

        :source vimsh.vim

    It is much easier to assign a key mapping to load it.  <Leader> is what
    ever you use as your leader sequence, I personally use '\'.

    A useful mapping might be:

         nmap <Leader>sh           :source <path_to_script>/vimsh.vim<CR>

    I use one like this:

         nmap \sh                  :source <path_to_script>/vimsh.vim<CR>

    There is a python script, vimsh.py, that needs to be in the same directory
    as vimsh.vim.  It should have been included in the .tar.gz or .zip file
    you downloaded as well as this file, a TODO file, and the CHANGELOG.

    Putting the scripts in your plugin directory is *NOT* recommended.

    You can also have multiple buffers using vimsh:

	    :VimShNewBuf foo

    will create a new additional vimsh buffer with the name _foo_.

:: vimsh license ::

    Use at your own risk.  I'm not responsible if it hoses your
    machine.  All I ask is that I'm made aware of changes so I can
    incorporate them into my version, that and my contact info stays in 
    the script.

:: vimsh limitations ::

    Running a shell within vim has it's limitations due to the fact
    that vim doesn't have the code necessary to run an interactive
    shell.  vimsh uses different methods to allow this to happen
    using python.

    general limitations:

        Can only execute line oriented programs, no vim within vim stuff,
        or non text-only interactive programs emacs, [n]curses apps, pagers, 
        etc.

    pty:

        The best support and formatting.  Most UNIX platforms support ptys.
        You can run interactive line based commands like ftp, telnet, rm,
        ping, cp, ssh, etc.  
        
        Only current limitation is involving commands that have
        continuous output (ping) or slow commands (ftp). You will need
        to use the refresh key (F5, remappable) to see output sometimes.
        I've tried everything I can possibly think of to try and get it
        to work but nothing has. See vimsh.vim for what's been tried,
        I'm open to suggestions. If vim ever gets an idle processing
        function, akin to CursorHold, but without the limitations, this
        will work properly.

    popen:

        Only non-interactive programs are supported.  Since this mostly applies
        to the Windows platform, this means you can run programs like:

            dir, findstr, type, attrib, set, ping, etc.  
            
            Interactive programs like ftp, telnet, ssh will *not* work
            correctly.

        This is because these programs seem to use buffered output or write
        directly to the console using the Windows Console API.  Unfortunately,
        this means that without pty functionality for windows ( or a lot of
        work on my part ), these commands cannot be run within vimsh.

        Also commands that wait on standard input currently cannot
        be interrupted w/ ctrl-c.  i.e. running 'findstr foo', since
        there is no file specified the command will wait and hang the shell
        session within vim.  Just delete the buffer if this happens (:bd).

:: vimsh customization ::

    It is recommended not to modify the vimsh.py or vimsh.vim to customize
    vimsh.  Support exists in vimsh to retreive settings that have been
    set in your .[g]vimrc or equivalent. 

    Here are some examples of how it would look in a .vimrc:

          let g:vimsh_prompt_override = 1               ##  will not use normal prompt from your 'real' shell
          let g:vimsh_prompt_pty      = "%m%#"          ##  specify overriden prompt
          let g:vimsh_split_open      = 0               ##  run vimsh in the current buffer
          let g:vimsh_sh              = "/bin/zsh"      ##  shell to run within vimsh

    The list of variables can be seen @ the bottom of vimsh.py.
    Look for the section in the file labeled 'customization'.

    Also note that by default on UNIX platforms, vimsh will use the
    $SHELL environment variable. If that environment variable is
    not set, /bin/sh is used. Setting vimsh_sh as shown above takes
    precedence over $SHELL. i.e. setting $SHELL to /usr/bin/python will
    launch python as your interpreter when starting a vimsh buffer.  Please
    note that you *must* use the fully qualified name in $SHELL.  i.e.
    /usr/bin/python not just python.  The easiest way to determine the fully
    qualified path to the shell is to type "which <app_name>".

:: vimsh notes ::

    The timeouts for reading are set low ( <= 0.2 sec ) for local filesystem
    and application use. If you plan on running telnet/ftp/ssh etc, pretty
    much any network based app, you can bump up the timeouts if you
    have a slower connection.  This is not an exact science. If you're not
    seeing all of the output or having to hit enter to see output you can
    bump the timeout up.  Being conservative won't hurt. See the mappings for
    setting the timeouts for reads and refreshing output.  If you don't want
    to change the timeouts you can just press <Enter> or <F5> (or whatever you
    have mapped the page output key to) to check for more output from the 
    command.

:: vimsh tips ::

    If you run tcsh or csh the following will allow you to have a better
    environment when using vimsh.

    Add these to your .vimrc:

        let g:vimsh_pty_prompt_override = 0
        let g:vimsh_sh                  = '/bin/tcsh'
        let $VIMSH                      = 1

    The $VIMSH can then be detected in your .cshrc to do special processing.
    For instance, vimsh doesn't support ANSI escape sequences yet so I unalias
    ls with color:

        if ($?VIMSH) then 
            unalias ls
        endif   

:: vimsh help ::

    Feel free to email me (bsturk@acomcast.net) with issues regarding    
    vimsh or if you've found a bug etc.  Please read this file, the          
    CHANGELOG, and the TODO to see if I already know about the issue, or    
    is a known limitation before contacting me.  If you do email me please   
    include the output of :ver from vim, the version of python you have     
    installed, what operating system you are running, and the output
    of running vimsh w/ _DEBUG_ set to 1 in vimsh.py in your email. 

:: vimsh info ::

    The latest version is always available @
        http://home.comcast.net/~bsturk/vim.html
       
    Please send bug reports, suggestions, and other email to
        bsturk@comcast.net