+++ /dev/null
-*screenpaste.txt* Paste/insert GNU Screen buffer in (almost) any mode v5.92
-
-Author: Christian Ebert <blacktrash@gmx.net>
-
-
- SCREENPASTE REFERENCE MANUAL~
-
-*screenpaste* *screenpaste.vim*
-
-==============================================================================
-
-1. Contents *screenpaste-toc*
-
- Screen Paste Plugin |screenpaste-intro|
- Activation |screenpaste-activate|
- Usage |screenpaste-usage|
- Options |screenpaste-options|
- Changing Mappings |screenpaste-mappings|
- Commands |screenpaste-commands|
- Bugs and Limitations |screenpaste-bugs|
- Credits |screenpaste-credits|
-
-==============================================================================
-
-2. Screen Paste Plugin *screenpaste-intro*
-
-The terminal window manager Screen http://www.gnu.org/software/screen
-offers the capability to copy and paste between windows.
-
-In principle you can just do "C-a ]" (default) to paste the current Screen
-buffer into a vim buffer. However this gives unexpected results when 'paste'
-is not set or in Vim's command-line.
-
-This script provides mappings and commands to get correct results.
-
-As an additional feature the current Screen buffer is available in any Vim
-instance, even those /outside/ the current Screen session.
-
-When pasting into command-line in Vim7 many commands are autodetected and the
-behaviour adapts automatically (|getcmdtype()|).
-
-The underlying mechanism of screenpaste consists in getting hold of the
-current Screen buffer via calling to Screen to write it to a temporary file.
-At this point Vim takes over, reads the contents of the file, and puts them to
-use either directly (in Insert, Replace or Command-line mode) or, in Normal
-and Visual mode, by writing to a register and, most often, putting the
-contents of the register into the Vim buffer. Which is why the default
-keybindings mimic |p|, |P|, |gp|, |gP|, with the |mapleader| prepended, as
-well as |:ScreenPut| and |:ScreenYank| behave almost like |:put| and |:yank|
-respectively.
-
-==============================================================================
-
-3. Activation *screenpaste-activate*
-
-Either copy screenpaste.vim to your plugin directory (|add-global-plugin|),
-or to your macros directory and source it (manually or from |vimrc|): >
- :runtime macros/screenpaste.vim
-or >
- :source $HOME/.vim/macros/screenpaste.vim
-
-The Vim Help documentation installs itself when you restart Vim.
-
-The GNU Screen executable has to be in $PATH. Otherwise screenpaste bails out
-giving an error message.
-
-==============================================================================
-
-4. Usage *screenpaste-usage*
-
-Think of the current Screen buffer as of a register at your disposal via the
-|screenpaste| mappings and commands.
-
- *screenpaste-put*
-When you type the plugin's Ex command
->
- :ScreenPut
-
-this works like executing |:put| with the current Screen buffer as register.
-It puts the text after the current line. Like |:put| it accepts a prepended
-number as parameter designating the target line as well as an appended bang
-to put the text before the indicated line and an optional register argument
-which defaults to |screen_register| when omitted.
-
-|:ScreenPut| differs from |:put| as the register is not only written into the
-buffer but filled with the current Screen buffer beforehand.
-
- *screenpaste-yank*
-If you want to just get hold of the current Screen buffer for further
-processing, type
->
- :ScreenYank
->
-and the Screen buffer is at your disposal in the |screen_register|. Similar
-to |:yank| you can also execute the command with an explicit register
-argument.
-
-Note: Screen's copy mechanism discards spaces at the end and the beginning of
-a selection in case there are printable characters in the same line. In Vim
-terms one could consider this like selecting 'exclusive', and to get a
-|linewise| "yank" the selection has to span visually more than one line, the
-newline at the end of a visually selected single line is not included.
-
-
-All other commands configure the treatment of the current Screen buffer when
-it is pasted into the command-line. Please refer to |screen_clmode| and
-|screenpaste-commands| for further information.
-
-
-Mappings:~
-
-In |Insert|, |Replace|, and |Command-line| modes (by default) simply type: >
- \p
-to paste the current Screen buffer. In these modes the |screen_register| is
-not changed.
-
-Note: mappings are ignored in Insert mode while |'paste'| is set. But in that
-case Screen's "paste" command (bound to "C-a]" by default) works just fine and
-there's no need to work around this via |'pastetoggle'|.
-
-
-The plugin's mappings for |Normal| and |Visual| mode emulate the non-Ex
-commands |p|, |P|, |gp|, and |gP|: They put the text of the current Screen
-buffer after or before the cursor, or replace the visual selection with it,
-just as if the unnamed register would contain the current Screen buffer (see
-|screen_register|).
-
-If the Screen buffer is empty they do nothing, the registers stay untouched,
-and only a corresponding message is displayed in the menu.
-
-Note however that the optional initial [count] argument to the original non-Ex
-commands will not work with these mappings (|screenpaste-bugs|).
-
-In their default state the |Normal| and |Visual| mode mappings consist of the
-same letters as the corresponding non-Ex commands with the |mapleader|
-prepended: >
-
- <Leader>p
- <Leader>P (not in Visual)
- <Leader>gp
- <Leader>gP (not in Visual)
-
-For simplicity we use the default |screenpaste-mappings| and the default
-|<Leader>| "\" in the following description.
-
- *screenpaste-p*
-\p Put current Screen buffer after the cursor.
-
- *screenpaste-P*
-\P Put current Screen buffer before the cursor.
- Not available in Visual mode.
-
- *screenpaste-gp*
-\gp Like "\p" but leave the cursor after the pasted text.
-
- *screenpaste-gP*
-\gP Like "\P" but leave the cursor after the pasted text.
- Not available in Visual mode.
-
-In |Visual| mode we do not need "\P" and "\gP" as "\p" and "\P" have the same
-effect of replacing the Visual selected text with the current Screen buffer.
-
-
-To summarize, supposing the default |<Leader>| "\" and the default
-|screenpaste-mappings| you can type:
->
- \p in Normal mode to put Screen buffer after cursor
- \gp in Normal mode to put Screen buffer after cursor and leave cursor
- after the end of new text
- \P in Normal mode to put Screen buffer before cursor
- \gP in Normal mode to put Screen buffer before cursor and leave cursor
- after the end of new text
- \p in Visual mode to replace visual selection with Screen buffer
- \gp in Visual mode to put Screen buffer after cursor and leave cursor
- after the end of new text
- \p in Insert and Replace mode to paste Screen buffer
- \p in Command-line-mode to put Screen buffer in command line
-
-==============================================================================
-
-5. Options *screenpaste-options*
-
-g:loaded_screenpaste *loaded_screenpaste*
-
- This option normally is set by screenpaste to avoid loading the script
- more than once. But you can use it to get the current script version: >
- :echo loaded_screenpaste
-<
- If you want to disable screenpaste, put the following line in your
- |vimrc|: >
- let g:loaded_screenpaste = 1
-
-g:screen_executable *screen_executable*
-
-Type String
-Default Value 'screen'
-
- Set this option if the name of your GNU Screen executable differs from
- "screen", or if you like to specify it's full path: >
- let g:screen_executable = "/usr/local/bin/screen"
-
-g:screen_visualselect *screen_visualselect*
-Type Boolean
-Default Value 0
-
- If set to 1 and in Visual mode the text from the Screen buffer is
- visually selected after the put operation.
-
-g:screen_register *screen_register*
-
-Type String
-Valid Values "a-z0-9A-Z
-Default Value '"'
-
- The non-Ex put "commands" (mappings) act in a twofold operation when
- executed in Normal or Visual mode: they yank the Screen buffer into a
- register in the background, and then put the register into the buffer
- or command-line. This variable controls the register that is used for
- the first part of the operation. It defaults to the unnamed register
- "" (|quotequote|).
-
- Normally you should be fine with the default setting. But if you
- prefer to reserve a register of your choice for the Screen buffer you
- can do so with this option. Besides the default "", you may choose
- any named (|quote_alpha|) or numbered (|quote_number|) register.
- Consult |registers| about their behaviour.
-
- For a one time operation with a special register the use of
- |ScreenPut| ex-command and its register argument is recommended.
-
- Note: Due to the mechanics of the script even a numbered register has
- to be passed as string, ie. it has to quoted when you set it; eg. >
- :let g:screen_register = "8"
-< Note as well that specifying an uppercase letter means that the
- contents of the Screen buffer will be appended to the register named
- with the corresponding lowercase character (|quote_alpha|).
-
-g:screen_clmode *screen_clmode*
-
-Type String
-Valid Values 'search', 'sub', 'noesc'
-Default Value 'search'
-
- This setting controls how the Screen buffer is treated when pasted in
- the command line.
-
- You can change the setting at startup in your |vimrc|: >
- let g:screen_clmode = "sub"
-<
- To change its value in a vim session you might want to use one of the
- |:ScreenCmdlineConf|, |:ScreenSearch|, |:ScreenSub|, |:ScreenNoEsc|
- commands as they also give a short informative message on how the mode
- of your choice will act, and prevent you from setting an invalid value.
-
- Information on the current value and the resulting behaviour is also
- available via the |:ScreenCmdlineInfo| command.
-
-Modes and their behaviour:
- *screenpaste-search*
-'search' ~
- Converts end-of-line to literal '\n'.
- Escapes characters according to the current setting of 'magic':
- magic: [ ] / \ ^ * . ~ $
- nomagic: ] / \ ^ $
-
- Use this mode to search for occurrences of current Screen buffer.
- Example as typed using default mapleader: >
- :ScreenSearch
- :%s/\p/repl/g
-< If the current Screen buffer is `[hello world.]' and 'magic' is set,
- the above becomes: >
- :%s/\[hello world\.\]/repl/g
-< *screenpaste-sub*
-'sub' ~
- Converts end-of-line to literal '\r'.
- Escapes characters according to the current setting of 'magic':
- magic: / \ ~ &
- nomagic: / \
-
- Use this mode to substitute a pattern with current Screen buffer.
- Example as typed using default mapleader: >
- :ScreenSub
- :%s/pattern/\p/g
-< If the current Screen buffer is `http://www.vim.org', the above
- becomes: >
- :%s/pattern/http:\/\/www.vim.org/g
-< *screenpaste-noesc*
-'noesc' ~
- Converts end-of-line to literal '\n'.
-
- Use this mode to paste current Screen buffer literally into command
- line.
-
-Vim7:
- |/|, |?|, |input()|, |:insert|, and |:append| commands are
- autodetected when not in 'noesc' |screen_clmode|. This means that even
- when you are in 'sub' mode you can type: >
- /\p
-< and this becomes (using above example for 'search'): >
- /\[hello world\.\]
-<
- Note: If you paste a Screen buffer containing newlines while in an
- |:insert| or |:append| but outside a running Screen session the
- newlines are escaped because we cannot call Screen's paste mechanism
- without clobbering a parallel Screen session, and Vim would insert
- <Nul> characters instead (see |NL-used-for-Nul|).
-
-Vim6:
- For |:insert| and |:append| commands use Screen's "C-a ]"
-
-==============================================================================
-
-6. Changing Mappings *screenpaste-mappings*
- *ScreenpastePut*
- *ScreenpasteGPut*
- *ScreenpastePutBefore*
- *ScreenpasteGPutBefore*
-
-The right-hand-side |{rhs}| mappings provided by this plugin and the modes in
-which to apply them are: >
-
- <Plug>ScreenpastePut Normal, Visual, Insert, Command-line
- <Plug>ScreenpasteGPut Normal, Visual
- <Plug>ScreenpastePutBefore Normal
- <Plug>ScreenpasteGPutBefore Normal
-<
-Use these to customize the default mappings <Leader>p, <Leader>gp, <Leader>P,
-and <Leader>gP to your taste (see |using-<Plug>| and |:map-modes|).
-
-The default mappings would look like this in a |vimrc|:
-
-map <Leader>p <Plug>ScreenpastePut " Normal, Visual mode
-map! <Leader>p <Plug>ScreenpastePut " Insert, Command-line mode
-map <Leader>gp <Plug>ScreenpasteGPut " Normal, Visual mode
-nmap <Leader>P <Plug>ScreenpastePutBefore " Normal mode
-nmap <Leader>gP <Plug>ScreenpasteGPutBefore " Normal mode
-
-You can tweak them by changing their left-hand-side |{lhs}|.
-
-Normal (put after cursor) and Visual mode:
- default
-:map {lhs} <Plug>ScreenpastePut \p
-:map {lhs} <Plug>ScreenpasteGPut \gp
-
- Vimrc example: >
- map <Leader>P <Plug>ScreenpastePut
-
-Normal mode (put before cursor):
-
-:nmap {lhs} <Plug>ScreenpastePutBefore \P
-:nmap {lhs} <Plug>ScreenpasteGPutBefore \gP
-
- Vimrc example: >
- nmap <Leader>I <Plug>ScreenpastePutBefore
-
-Insert and Command-line mode:
-
-:map! {lhs} <Plug>ScreenpastePut \p
-
- Vimrc example, to avoid character mappings when inserting: >
- map! <F7> <Plug>ScreenpastePut
-
-==============================================================================
-
-7. Commands *screenpaste-commands*
-
- *:ScreenYank*
-:ScreenYank [x] Yank current Screen buffer into register [x] (default
- |screen_register|).
-
- *:ScreenPut*
-:[line]ScreenPut [x] Put the text from current Screen buffer after [line]
- (default current line) using register [x] (default
- |screen_register|).
-
- You can use this command for instance to append the contents of the
- Screen buffer to a named register and then paste in one go: >
- :3 ScreenPut A
-< puts the contents of register "a and the Screen buffer after line 3.
-
-:[line]ScreenPut! [x] Put the text from current Screen buffer before [line]
- (default current line) using register [x] (default
- |screen_register|).
-
- *:ScreenCmdlineConf*
-:ScreenCmdlineConf {mode}
- Tell screenpaste to convert the current Screen
- buffer in command-line-mode according to {mode}.
- Takes one argument of: "search", "sub", "noesc" (w/o
- quotes).
- Changes |screen_clmode| accordingly.
- Example: >
- :ScreenCmdlineConf noesc
-<
- *:ScreenCmdlineInfo*
-:ScreenComdlineInfo Display information on current command-line-mode
- behaviour, ie. current |screen_clmode| and what it
- does.
-
- *:ScreenSearch*
-:ScreenSearch Set |screen_clmode| to 'search'.
- Equivalent to: >
- :ScreenCmdlineConf search
-<
- *:ScreenSub*
-:ScreenSub Set |screen_clmode| to 'sub'.
- Equivalent to: >
- :ScreenCmdlineConf sub
-<
- *:ScreenNoEsc*
-:ScreenNoEsc Set |screen_clmode| to 'noesc'.
- Equivalent to: >
- :ScreenCmdlineConf noesc
-
-==============================================================================
-
-8. Bugs and Limitations *screenpaste-bugs*
-
-Found no way (yet?) to make optional initial [count] argument work with
-(Normal mode) mappings.
-
-Screen's copy mechanism treats spaces (including newlines) at the beginning or
-the end of a selection in a different manner than Vim's visual yank does.
-
-Screen expands tabs, expect incorrect results if the Screen buffer contains
-tabs.
-
-==============================================================================
-
-Credits *screenpaste-credits*
-
-Mathieu Clabaut, Guo-Peng Wen let me steal and tweak the inline
- self-install code for this Help document.
-
-==============================================================================
-
- vim:tw=78:ts=8:ft=help:norl:
ruderich.org/simon / config / dotfiles.git / blobdiff