summaryrefslogtreecommitdiffstats
path: root/.vim/doc
diff options
context:
space:
mode:
Diffstat (limited to '.vim/doc')
-rw-r--r--.vim/doc/screen.txt390
1 files changed, 390 insertions, 0 deletions
diff --git a/.vim/doc/screen.txt b/.vim/doc/screen.txt
new file mode 100644
index 0000000..12c78fe
--- /dev/null
+++ b/.vim/doc/screen.txt
@@ -0,0 +1,390 @@
+*screen.txt*
+
+Author: Eric Van Dewoestine <ervandew@gmail.com>
+
+This plugin is licensed under the terms of the BSD License. Please see
+screen.vim for the license in its entirety.
+
+-----------------------------------------------------------------------------
+Screen *screen*
+
+Introduction |screen-intro|
+Screen Usage |screen-usage|
+ :ScreenShell |screen-shell|
+ :ScreenShellAttach |screen-shellattach|
+ :ScreenSend |screen-send|
+ :ScreenQuit |screen-quit|
+Screen Options |screen-options|
+ Terminal muliplexer |screen-impl|
+ Shell height |screen-shellheight|
+ Quit on exit |screen-quitonexit|
+ External shell |screen-externalshell|
+ Server name |screen-servername|
+ Terminal |screen-terminal|
+Custom mappings |screen-mappings|
+Script integration |screen-scriptintegration|
+Gotchas |screen-gotchas|
+Troubleshooting |screen-troubleshooting|
+
+-----------------------------------------------------------------------------
+Introduction *screen-intro*
+
+This plugin aims to simulate an embedded shell in vim by allowing you to
+easily convert your current vim session into one running in gnu screen with a
+split gnu screen window containing a shell, and to quickly send
+statements/code to whatever program is running in that shell (bash, python,
+irb, etc.). Spawning the shell in your favorite terminal emulator is also
+supported for gvim users or anyone else that just prefers an external shell.
+
+Currently tested on Linux and Windows (win32 gvim and cygwin vim), but
+should also work on any unix based platform where screen is supported (OSX,
+BSD, Solaris, etc.). Note that in my testing of cygwin, invocations of screen
+were significantly slower and less fluid than on Linux. The Windows
+experience is better when using gvim to spawn a cygwin shell running screen.
+
+Tmux Users: On non-windows systems, tmux is also supported in place of gnu
+screen. To use tmux simply add the following to your vimrc:
+ let g:ScreenImpl = 'Tmux'
+
+ Note: With tmux, :ScreenShellAttach is currently not supported.
+
+Windows Users: Whether you are using gvim or not, you will need cygwin
+installed with cygwin's bin directory in your windows PATH.
+
+-----------------------------------------------------------------------------
+Screen usage *screen-usage*
+
+Here is a sample workflow utilizing screen.vim to execute some python code in
+the python interactive interpreter:
+
+ 1. Edit a python file
+ $ vim something.py
+
+ 2. Decide you want to run all or pieces of the code in an interactive python
+ shell
+ :ScreenShell python
+
+ 3. Send code from a vim buffer to the shell
+ :ScreenSend
+
+ 4. Quit the screen session and return to your original vim session
+ :ScreenQuit
+ or
+ :qa
+
+Below is a comprehensive list of the commands which screen.vim provides:
+
+:ScreenShell [cmd] *screen-shell* *:ScreenShell*
+ Starts a screen hosted shell performing the following steps depending on
+ your environment.
+
+ When running a console vim on a unix based OS (Linux, BSD, OSX):
+ 1. save a session file from your currently running vim instance
+ (current tab only)
+ 2. start gnu screen with vim running in it
+ 3. load your saved session file
+ 4. create a lower gnu screen split window and start a shell, or if
+ g:ScreenShellExternal is set, start an external terminal with
+ screen running.
+ 5. if a command was supplied to :ScreenShell, run it in the new
+ shell.
+ Ex. :ScreenShell ipython
+
+ Note: If you are already in a gnu screen session, then only steps
+ 4 and 5 above will be run.
+
+ When running gvim:
+ 1. start an external terminal with screen running.
+ 2. if a command was supplied to :ScreenShell, run it in the new
+ shell.
+ Ex. :ScreenShell ipython
+
+:ScreenShellVertical [cmd] *screen-shell-vertical* *:ScreenShellVertical*
+ Just like |:ScreenShell| but when creating the split region for the shell, a
+ vertical split is used instead of the default horizontal split. Supported
+ via tmux by default, but gnu screen requires the vertical split patch
+ (http://fungi.yuggoth.org/vsp4s/) or the unreleased screen 4.1 code and you
+ must explicitly enable support for gnu screen vertical splitting in
+ screen.vim by adding the following to your vimrc, indicating whether you are
+ using a patched gnu screen or the 4.1 code base:
+ let g:ScreenShellGnuScreenVerticalSupport = 'patch'
+ or
+ let g:ScreenShellGnuScreenVerticalSupport = 'native'
+
+
+:ScreenShellAttach [session] *screen-shellattach* *:ScreenShellAttach*
+ Sets the necessary internal variables to allow :ScreenSend invocations to
+ send to the specified screen session. If no session is provided, then the
+ first session found is used. If the session is in the "Detached" state,
+ then a new terminal is opened with a new screen instance attached to the
+ session. Attaching to a detached session is not currently supported on
+ windows due to deficiencies in the cygwin version of gnu screen.
+
+ Note: for screen sessions attached to via this mechanism, :ScreenSend
+ invocations will send the text to the active screen window instead of
+ targeting the 'shell' window when used from :ScreenShell. However, this
+ behavior can be configured via the g:ScreenShellAttachTargetCurrent
+ variable, which when non 0, will set the title on the currently focused gnu
+ screen window and target it for all send commands.
+
+:ScreenSend
+ Send the visual selection or the entire buffer contents to the running gnu
+ screen shell window.
+
+:ScreenQuit
+ Save all currently modified vim buffers and quit gnu screen, returning you
+ to your previous vim instance running outside of gnu screen
+
+ Note: :ScreenQuit is not available if you where already in a gnu
+ screen session when you ran :ScreenShell.
+ Note: By default, if the gnu screen session was started by
+ :ScreenShell, then exiting vim will quit the gnu screen session as
+ well (configurable via g:ScreenShellQuitOnVimExit).
+
+
+-----------------------------------------------------------------------------
+Screen Options *screen-options*
+
+Screen is configured via several global variables that you can set in your
+|vimrc| file according to your needs. Below is a comprehensive list of the
+variables available.
+
+Terminal Multiplexer *screen-impl*
+ *g:ScreenImpl*
+
+g:ScreenImpl (default value: 'GnuScreen')
+
+This sets the name of the terminal multiplexer you want to use. Support
+values include 'GnuScreen' or 'Tmux'.
+
+
+Shell height *screen-shellheight*
+ *g:ScreenShellHeight*
+
+g:ScreenShellHeight (default value: 15)
+
+Sets the height of the gnu screen (or tmux) region used for the shell. When
+the value is less than or equal to 0, then half of vim's reported window
+height will be used.
+
+
+Shell width *screen-shellwidth*
+ *g:ScreenShellWidth*
+
+g:ScreenShellWidth (default value: -1)
+
+Sets the width of the gnu screen (or tmux) region used for the shell when
+splitting the region vertically (vertical split support in gnu screen requires
+the vertical split patch). When the value is less than or equal to 0, then
+half of vim's reported window width will be used.
+
+
+Quit on exit *screen-quitonexit*
+ *g:ScreenShellQuitOnVimExit*
+
+g:ScreenShellQuitOnVimExit (default value: 1)
+
+When non-zero and the gnu screen (or tmux) session was started by this script,
+the screen session will be closed when vim exits.
+
+
+External Shell *screen-externalshell*
+ *g:ScreenShellExternal*
+
+g:ScreenShellExternal (default value: 0)
+
+When non-zero and not already in a screen session, an external shell will be
+spawned instead of using a split region for the shell. Note: when using gvim,
+an external shell is always used.
+
+
+Initial focus *screen-focus*
+ *g:ScreenShellInitialFocus*
+
+g:ScreenShellInitialFocus (default value: 'vim')
+
+When set to 'shell' the newly created shell region will be focused when first
+creating the shell region.
+
+
+Server Name *screen-servername*
+ *g:ScreenShellServerName*
+
+g:ScreenShellServerName (default value: 'vim')
+
+If the gnu screen session is started by this plugin, then the value of this
+setting will be used for the servername arg of the vim instance started in the
+new gnu screen session (not applicable for gvim users). The default is 'vim'
+unless you have g:ScreenShellExternal enabled, in which case, if you still
+want to restart vim in a screen session with a servername, then simply set
+this variable in your vimrc.
+
+
+Terminal *screen-terminal*
+ *g:ScreenShellTerminal*
+
+g:ScreenShellTerminal (default value: '')
+
+When g:ScreenShellExternal is enabled or you are running gvim, this value will
+be used as the name of the terminal executable to be used. If this value is
+empty, a list of common terminals will be tried until one is found.
+
+
+Expand Tabs *screen-expandtabs*
+ *g:ScreenShellExpandTabs*
+
+g:ScreenShellExpandTabs (default value: 0)
+
+When sending text from vim to an external program, that program may interpret
+tabs as an attempt to perform completion resulting in the text sent not
+performing the function you intended. As a work around, you can set this
+setting to a non 0 value resulting in all tabs being expanded to spaces before
+sending the text to screen/tmux.
+
+-----------------------------------------------------------------------------
+Custom Mappings *screen-mappings*
+
+Defining custom key mappings for for screen.vim can be accomplished like with
+any other plugin: >
+ nmap <C-c><C-c> :ScreenShell<cr>
+>
+
+But you may want to have different mappings depending on the whether you have
+an active screen shell open or not. For this case screen.vim provides a couple
+autocmd groups which you can use to listen for entering or exiting of a screen
+shell session. Here is an example which sets some global key bindings based
+on the screen shell state: >
+
+ function! s:ScreenShellListener()
+ if g:ScreenShellActive
+ nmap <C-c><C-c> :ScreenSend<cr>
+ nmap <C-c><C-x> :ScreenQuit<cr>
+ else
+ nmap <C-c><C-c> :ScreenShell<cr>
+ endif
+ endfunction
+
+ nmap <C-c><C-c> :ScreenShell<cr>
+ augroup ScreenShellEnter
+ autocmd User * call <SID>ScreenShellListener()
+ augroup END
+ augroup ScreenShellExit
+ autocmd User * call <SID>ScreenShellListener()
+ augroup END
+>
+
+You can also take this a step further and do the same as the above, but do so
+on a per filetype basis, where the key binding are buffer local and interact
+with the filetype's associated interpreter. Here is an example which can be
+put in a python ftplugin: >
+
+ function! s:ScreenShellListener()
+ if g:ScreenShellActive
+ if g:ScreenShellCmd == 'python'
+ nmap <buffer> <C-c><C-c> :ScreenSend<cr>
+ else
+ nmap <buffer> <C-c><C-c> <Nop>
+ endif
+ else
+ nmap <buffer> <C-c><C-c> :ScreenShell python<cr>
+ endif
+ endfunction
+
+ call s:ScreenShellListener()
+ augroup ScreenShellEnter
+ autocmd User *.py call <SID>ScreenShellListener()
+ augroup END
+ augroup ScreenShellExit
+ autocmd User *.py call <SID>ScreenShellListener()
+ augroup END
+>
+
+Note how the :ScreenShell mapping starts the python interpreter. Before
+mapping the :ScreenSend command, the function also checks if the shell was
+started with the 'python' command, allowing you to unmap (<Nop> in this case
+to counter act any global defined mapping) the send command if some other
+shell command is running (irb, lisp interpreter, etc).
+
+-----------------------------------------------------------------------------
+Script Integration *screen-scriptintegration*
+
+To permit integration with your own, or 3rd party, scripts, a funcref is made
+globally available while the screen shell mode is enabled, allowing you to
+send your own strings to the attached shell.
+
+Here are some examples of using this funcref to send some commands to bash: >
+ :call ScreenShellSend("echo foo\necho bar")
+ :call ScreenShellSend('echo -e "foo\nbar"')
+ :call ScreenShellSend("echo -e \"foo\\nbar\"")
+>
+
+Sending a list of strings is also supported: >
+ :call ScreenShellSend(["echo foo", "echo bar"])
+>
+
+You can test that the funcref exists using: >
+ exists('ScreenShellSend')
+>
+
+In addition to sending text to the screen shell, another funcref is available
+allowing you to focus the shell region in screen. Note: focusing an external
+screen shell is not supported.
+
+To focus the shell region from vim you can invoke the funcref like so: >
+ :call ScreenShellFocus()
+>
+
+This will focus the bottom most region which is expected to be the one running
+your shell or other program.
+
+
+-----------------------------------------------------------------------------
+Gotchas *screen-gotchas*
+
+While running vim in gnu screen, if you detach the session instead of
+quitting, then when returning to the non-screen vim, vim will complain about
+swap files already existing. So try to avoid detaching.
+
+Not all vim plugins support saving state to or loading from vim session files,
+so when running :ScreenShell some buffers may not load correctly if they are
+backed by such a plugin.
+
+
+-----------------------------------------------------------------------------
+Troubleshooting *screen-troubleshooting*
+
+Below are a list of possible issues you may encounter and some info on
+resolving those issues.
+
+- When already in a screen session, running :ScreenShell results in a nested
+ screen session instead of using the existing one.
+ *screen-bootstrap*
+
+ When running :ScreenShell from a console version of vim, screen.vim examines
+ the $TERM environment variable which it expects to start with 'screen'
+ ('screen', 'screen-256color', etc.) if you are in an existing screen/tmux
+ session. Should the TERM value not start with 'screen', then screen.vim
+ assumes that a screen session must be started for you.
+
+ The cause of TERM not containing a 'screen' values is usually the result of
+ having a non-screen term value in your ~/.screenrc or the term value you are
+ using doesn't have a corresponding terminfo file resulting in $TERM being
+ set to some other value. Take a look at the |screen-256color| docs below for
+ more information.
+
+- 256 color support *screen-256color*
+
+ To enable 256 color support in screen you'll need to add the following to
+ your ~/.screenrc:
+
+ term screen-256color
+
+ Please note that this will set your $TERM to 'screen-256color' which will
+ require that your system has a corresponding terminfo file. Not all systems
+ have this installed by default so you may need to install an additional
+ package:
+
+ ubuntu - $ apt-get install ncurses-term
+
+
+vim:tw=78:ts=8:ft=help:norl: