X-Git-Url: https://ruderich.org/simon/gitweb/?a=blobdiff_plain;f=doc%2Fscreenpaste.txt;h=49cfeb61471cad5dd7f32c747c0504ff92d7bbe5;hb=HEAD;hp=11a50e8d10cae5aa1a6831cd13f5a3bb1c00a1af;hpb=be5e5699cd87f69e83df57bd6e08f415afc6ddd2;p=config%2Fdotfiles.git diff --git a/doc/screenpaste.txt b/doc/screenpaste.txt deleted file mode 100644 index 11a50e8..0000000 --- a/doc/screenpaste.txt +++ /dev/null @@ -1,437 +0,0 @@ -*screenpaste.txt* Paste/insert GNU Screen buffer in (almost) any mode v5.92 - -Author: Christian Ebert - - - 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: > - - p - P (not in Visual) - gp - gP (not in Visual) - -For simplicity we use the default |screenpaste-mappings| and the default -|| "\" 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 || "\" 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 - 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: > - - ScreenpastePut Normal, Visual, Insert, Command-line - ScreenpasteGPut Normal, Visual - ScreenpastePutBefore Normal - ScreenpasteGPutBefore Normal -< -Use these to customize the default mappings p, gp, P, -and gP to your taste (see |using-| and |:map-modes|). - -The default mappings would look like this in a |vimrc|: - -map p ScreenpastePut " Normal, Visual mode -map! p ScreenpastePut " Insert, Command-line mode -map gp ScreenpasteGPut " Normal, Visual mode -nmap P ScreenpastePutBefore " Normal mode -nmap gP ScreenpasteGPutBefore " Normal mode - -You can tweak them by changing their left-hand-side |{lhs}|. - -Normal (put after cursor) and Visual mode: - default -:map {lhs} ScreenpastePut \p -:map {lhs} ScreenpasteGPut \gp - - Vimrc example: > - map P ScreenpastePut - -Normal mode (put before cursor): - -:nmap {lhs} ScreenpastePutBefore \P -:nmap {lhs} ScreenpasteGPutBefore \gP - - Vimrc example: > - nmap I ScreenpastePutBefore - -Insert and Command-line mode: - -:map! {lhs} ScreenpastePut \p - - Vimrc example, to avoid character mappings when inserting: > - map! 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: