]> ruderich.org/simon Gitweb - config/dotfiles.git/blob - vim/bundle/screenpaste/doc/screenpaste.txt
11a50e8d10cae5aa1a6831cd13f5a3bb1c00a1af
[config/dotfiles.git] / vim / bundle / screenpaste / doc / screenpaste.txt
1 *screenpaste.txt* Paste/insert GNU Screen buffer in (almost) any mode  v5.92
2
3 Author: Christian Ebert <blacktrash@gmx.net>
4
5
6                 SCREENPASTE REFERENCE MANUAL~
7
8 *screenpaste* *screenpaste.vim*
9
10 ==============================================================================
11
12 1. Contents                                             *screenpaste-toc*
13
14         Screen Paste Plugin                             |screenpaste-intro|
15         Activation                                      |screenpaste-activate|
16         Usage                                           |screenpaste-usage|
17         Options                                         |screenpaste-options|
18         Changing Mappings                               |screenpaste-mappings|
19         Commands                                        |screenpaste-commands|
20         Bugs and Limitations                            |screenpaste-bugs|
21         Credits                                         |screenpaste-credits|
22
23 ==============================================================================
24
25 2. Screen Paste Plugin                                  *screenpaste-intro*
26
27 The terminal window manager Screen http://www.gnu.org/software/screen
28 offers the capability to copy and paste between windows.
29
30 In principle you can just do "C-a ]" (default) to paste the current Screen
31 buffer into a vim buffer. However this gives unexpected results when 'paste'
32 is not set or in Vim's command-line.
33
34 This script provides mappings and commands to get correct results.
35
36 As an additional feature the current Screen buffer is available in any Vim
37 instance, even those /outside/ the current Screen session.
38
39 When pasting into command-line in Vim7 many commands are autodetected and the
40 behaviour adapts automatically (|getcmdtype()|).
41
42 The underlying mechanism of screenpaste consists in getting hold of the
43 current Screen buffer via calling to Screen to write it to a temporary file.
44 At this point Vim takes over, reads the contents of the file, and puts them to
45 use either directly (in Insert, Replace or Command-line mode) or, in Normal
46 and Visual mode, by writing to a register and, most often, putting the
47 contents of the register into the Vim buffer.  Which is why the default
48 keybindings mimic |p|, |P|, |gp|, |gP|, with the |mapleader| prepended, as
49 well as |:ScreenPut| and |:ScreenYank| behave almost like |:put| and |:yank|
50 respectively.
51
52 ==============================================================================
53
54 3. Activation                                           *screenpaste-activate*
55
56 Either copy screenpaste.vim to your plugin directory (|add-global-plugin|),
57 or to your macros directory and source it (manually or from |vimrc|): >
58         :runtime macros/screenpaste.vim
59 or >
60         :source $HOME/.vim/macros/screenpaste.vim
61
62 The Vim Help documentation installs itself when you restart Vim.
63
64 The GNU Screen executable has to be in $PATH. Otherwise screenpaste bails out
65 giving an error message.
66
67 ==============================================================================
68
69 4. Usage                                                *screenpaste-usage*
70
71 Think of the current Screen buffer as of a register at your disposal via the
72 |screenpaste| mappings and commands.
73
74                                                         *screenpaste-put*
75 When you type the plugin's Ex command
76 >
77         :ScreenPut
78
79 this works like executing |:put| with the current Screen buffer as register.
80 It puts the text after the current line.  Like |:put| it accepts a prepended
81 number as parameter designating the target line as well as an appended bang
82 to put the text before the indicated line and an optional register argument
83 which defaults to |screen_register| when omitted.
84
85 |:ScreenPut| differs from |:put| as the register is not only written into the
86 buffer but filled with the current Screen buffer beforehand.
87
88                                                         *screenpaste-yank*
89 If you want to just get hold of the current Screen buffer for further
90 processing, type
91 >
92         :ScreenYank
93 >
94 and the Screen buffer is at your disposal in the |screen_register|.  Similar
95 to |:yank| you can also execute the command with an explicit register
96 argument.
97
98 Note: Screen's copy mechanism discards spaces at the end and the beginning of
99 a selection in case there are printable characters in the same line.  In Vim
100 terms one could consider this like selecting 'exclusive', and to get a
101 |linewise| "yank" the selection has to span visually more than one line, the
102 newline at the end of a visually selected single line is not included.
103
104
105 All other commands configure the treatment of the current Screen buffer when
106 it is pasted into the command-line.  Please refer to |screen_clmode| and
107 |screenpaste-commands| for further information.
108
109
110 Mappings:~
111
112 In |Insert|, |Replace|, and |Command-line| modes (by default) simply type: >
113         \p
114 to paste the current Screen buffer.  In these modes the |screen_register| is
115 not changed.
116
117 Note: mappings are ignored in Insert mode while |'paste'| is set. But in that
118 case Screen's "paste" command (bound to "C-a]" by default) works just fine and
119 there's no need to work around this via |'pastetoggle'|.
120
121
122 The plugin's mappings for |Normal| and |Visual| mode emulate the non-Ex
123 commands |p|, |P|, |gp|, and |gP|:  They put the text of the current Screen
124 buffer after or before the cursor, or replace the visual selection with it,
125 just as if the unnamed register would contain the current Screen buffer (see
126 |screen_register|).
127
128 If the Screen buffer is empty they do nothing, the registers stay untouched,
129 and only a corresponding message is displayed in the menu.
130
131 Note however that the optional initial [count] argument to the original non-Ex
132 commands will not work with these mappings (|screenpaste-bugs|).
133
134 In their default state the |Normal| and |Visual| mode mappings consist of the
135 same letters as the corresponding non-Ex commands with the |mapleader|
136 prepended: >
137
138         <Leader>p
139         <Leader>P       (not in Visual)
140         <Leader>gp
141         <Leader>gP      (not in Visual)
142
143 For simplicity we use the default |screenpaste-mappings| and the default
144 |<Leader>| "\" in the following description.
145
146                                                         *screenpaste-p*
147 \p                      Put current Screen buffer after the cursor.
148
149                                                         *screenpaste-P*
150 \P                      Put current Screen buffer before the cursor.
151                         Not available in Visual mode.
152
153                                                         *screenpaste-gp*
154 \gp                     Like "\p" but leave the cursor after the pasted text.
155
156                                                         *screenpaste-gP*
157 \gP                     Like "\P" but leave the cursor after the pasted text.
158                         Not available in Visual mode.
159
160 In |Visual| mode we do not need "\P" and "\gP" as "\p" and "\P" have the same
161 effect of replacing the Visual selected text with the current Screen buffer.
162
163
164 To summarize, supposing the default |<Leader>| "\" and the default
165 |screenpaste-mappings| you can type:
166 >
167         \p  in Normal mode to put Screen buffer after cursor
168         \gp in Normal mode to put Screen buffer after cursor and leave cursor
169                 after the end of new text
170         \P  in Normal mode to put Screen buffer before cursor
171         \gP in Normal mode to put Screen buffer before cursor and leave cursor
172                 after the end of new text
173         \p  in Visual mode to replace visual selection with Screen buffer
174         \gp in Visual mode to put Screen buffer after cursor and leave cursor
175                 after the end of new text
176         \p  in Insert and Replace mode to paste Screen buffer
177         \p  in Command-line-mode to put Screen buffer in command line
178
179 ==============================================================================
180
181 5. Options                                              *screenpaste-options*
182
183 g:loaded_screenpaste                                    *loaded_screenpaste*
184
185         This option normally is set by screenpaste to avoid loading the script
186         more than once. But you can use it to get the current script version: >
187                 :echo loaded_screenpaste
188 <
189         If you want to disable screenpaste, put the following line in your
190         |vimrc|: >
191                 let g:loaded_screenpaste = 1
192
193 g:screen_executable                                     *screen_executable*
194
195 Type            String
196 Default Value   'screen'
197
198         Set this option if the name of your GNU Screen executable differs from
199         "screen", or if you like to specify it's full path: >
200                 let g:screen_executable = "/usr/local/bin/screen"
201
202 g:screen_visualselect                                   *screen_visualselect*
203 Type            Boolean
204 Default Value   0
205
206         If set to 1 and in Visual mode the text from the Screen buffer is
207         visually selected after the put operation.
208
209 g:screen_register                                       *screen_register*
210
211 Type            String
212 Valid Values    "a-z0-9A-Z
213 Default Value   '"'
214
215         The non-Ex put "commands" (mappings) act in a twofold operation when
216         executed in Normal or Visual mode: they yank the Screen buffer into a
217         register in the background, and then put the register into the buffer
218         or command-line.  This variable controls the register that is used for
219         the first part of the operation.  It defaults to the unnamed register
220         "" (|quotequote|).
221
222         Normally you should be fine with the default setting.  But if you
223         prefer to reserve a register of your choice for the Screen buffer you
224         can do so with this option.  Besides the default "", you may choose
225         any named (|quote_alpha|) or numbered (|quote_number|) register.
226         Consult |registers| about their behaviour.
227
228         For a one time operation with a special register the use of
229         |ScreenPut| ex-command and its register argument is recommended.
230
231         Note: Due to the mechanics of the script even a numbered register has
232         to be passed as string, ie. it has to quoted when you set it; eg. >
233                 :let g:screen_register = "8"
234 <       Note as well that specifying an uppercase letter means that the
235         contents of the Screen buffer will be appended to the register named
236         with the corresponding lowercase character (|quote_alpha|).
237
238 g:screen_clmode                                         *screen_clmode*
239
240 Type            String
241 Valid Values    'search', 'sub', 'noesc'
242 Default Value   'search'
243
244         This setting controls how the Screen buffer is treated when pasted in
245         the command line.
246
247         You can change the setting at startup in your |vimrc|: >
248                 let g:screen_clmode = "sub"
249 <
250         To change its value in a vim session you might want to use one of the
251         |:ScreenCmdlineConf|, |:ScreenSearch|, |:ScreenSub|, |:ScreenNoEsc|
252         commands as they also give a short informative message on how the mode
253         of your choice will act, and prevent you from setting an invalid value.
254
255         Information on the current value and the resulting behaviour is also
256         available via the |:ScreenCmdlineInfo| command.
257
258 Modes and their behaviour:
259                                                         *screenpaste-search*
260 'search' ~
261         Converts end-of-line to literal '\n'.
262         Escapes characters according to the current setting of 'magic':
263         magic:    [ ] / \ ^ * . ~ $
264         nomagic:    ] / \ ^       $
265
266         Use this mode to search for occurrences of current Screen buffer.
267         Example as typed using default mapleader: >
268                 :ScreenSearch
269                 :%s/\p/repl/g
270 <       If the current Screen buffer is `[hello world.]' and 'magic' is set,
271         the above becomes: >
272                 :%s/\[hello world\.\]/repl/g
273 <                                                       *screenpaste-sub*
274 'sub' ~
275         Converts end-of-line to literal '\r'.
276         Escapes characters according to the current setting of 'magic':
277         magic:    /  \  ~  &
278         nomagic:  /  \
279
280         Use this mode to substitute a pattern with current Screen buffer.
281         Example as typed using default mapleader: >
282                 :ScreenSub
283                 :%s/pattern/\p/g
284 <       If the current Screen buffer is `http://www.vim.org', the above
285         becomes: >
286                 :%s/pattern/http:\/\/www.vim.org/g
287 <                                                       *screenpaste-noesc*
288 'noesc' ~
289         Converts end-of-line to literal '\n'.
290
291         Use this mode to paste current Screen buffer literally into command
292         line.
293
294 Vim7:
295         |/|, |?|, |input()|, |:insert|, and |:append| commands are
296         autodetected when not in 'noesc' |screen_clmode|. This means that even
297         when you are in 'sub' mode you can type: >
298                 /\p
299 <       and this becomes (using above example for 'search'): >
300                 /\[hello world\.\]
301 <
302         Note: If you paste a Screen buffer containing newlines while in an
303         |:insert| or |:append| but outside a running Screen session the
304         newlines are escaped because we cannot call Screen's paste mechanism
305         without clobbering a parallel Screen session, and Vim would insert
306         <Nul> characters instead (see |NL-used-for-Nul|).
307
308 Vim6:
309         For |:insert| and |:append| commands use Screen's "C-a ]"
310
311 ==============================================================================
312
313 6. Changing Mappings                                    *screenpaste-mappings*
314                                                         *ScreenpastePut*
315                                                         *ScreenpasteGPut*
316                                                         *ScreenpastePutBefore*
317                                                         *ScreenpasteGPutBefore*
318
319 The right-hand-side |{rhs}| mappings provided by this plugin and the modes in
320 which to apply them are: >
321
322         <Plug>ScreenpastePut            Normal, Visual, Insert, Command-line
323         <Plug>ScreenpasteGPut           Normal, Visual
324         <Plug>ScreenpastePutBefore      Normal
325         <Plug>ScreenpasteGPutBefore     Normal
326 <
327 Use these to customize the default mappings <Leader>p, <Leader>gp, <Leader>P,
328 and <Leader>gP to your taste (see |using-<Plug>| and |:map-modes|).
329
330 The default mappings would look like this in a |vimrc|:
331
332 map  <Leader>p  <Plug>ScreenpastePut            " Normal, Visual mode
333 map! <Leader>p  <Plug>ScreenpastePut            " Insert, Command-line mode
334 map  <Leader>gp <Plug>ScreenpasteGPut           " Normal, Visual mode
335 nmap <Leader>P  <Plug>ScreenpastePutBefore      " Normal mode
336 nmap <Leader>gP <Plug>ScreenpasteGPutBefore     " Normal mode
337
338 You can tweak them by changing their left-hand-side |{lhs}|.
339
340 Normal (put after cursor) and Visual mode:
341                                                         default
342 :map    {lhs}   <Plug>ScreenpastePut                      \p
343 :map    {lhs}   <Plug>ScreenpasteGPut                     \gp
344
345         Vimrc example: >
346                 map  <Leader>P <Plug>ScreenpastePut
347
348 Normal mode (put before cursor):
349
350 :nmap   {lhs}   <Plug>ScreenpastePutBefore                \P
351 :nmap   {lhs}   <Plug>ScreenpasteGPutBefore               \gP
352
353         Vimrc example: >
354                 nmap <Leader>I <Plug>ScreenpastePutBefore
355
356 Insert and Command-line mode:
357
358 :map!   {lhs}   <Plug>ScreenpastePut                      \p
359
360         Vimrc example, to avoid character mappings when inserting: >
361                 map! <F7> <Plug>ScreenpastePut
362
363 ==============================================================================
364
365 7. Commands                                             *screenpaste-commands*
366
367                                                         *:ScreenYank*
368 :ScreenYank [x]         Yank current Screen buffer into register [x] (default
369                         |screen_register|).
370
371                                                         *:ScreenPut*
372 :[line]ScreenPut [x]    Put the text from current Screen buffer after [line]
373                         (default current line) using register [x] (default
374                         |screen_register|).
375
376         You can use this command for instance to append the contents of the
377         Screen buffer to a named register and then paste in one go: >
378                 :3 ScreenPut A
379 <       puts the contents of register "a and the Screen buffer after line 3.
380
381 :[line]ScreenPut! [x]   Put the text from current Screen buffer before [line]
382                         (default current line) using register [x] (default
383                         |screen_register|).
384
385                                                         *:ScreenCmdlineConf*
386 :ScreenCmdlineConf {mode}
387                         Tell screenpaste to convert the current Screen
388                         buffer in command-line-mode according to {mode}.
389                         Takes one argument of: "search", "sub", "noesc" (w/o
390                         quotes).
391                         Changes |screen_clmode| accordingly.
392         Example: >
393                 :ScreenCmdlineConf noesc
394 <
395                                                         *:ScreenCmdlineInfo*
396 :ScreenComdlineInfo     Display information on current command-line-mode
397                         behaviour, ie. current |screen_clmode| and what it
398                         does.
399
400                                                         *:ScreenSearch*
401 :ScreenSearch           Set |screen_clmode| to 'search'.
402         Equivalent to: >
403                 :ScreenCmdlineConf search
404 <
405                                                         *:ScreenSub*
406 :ScreenSub              Set |screen_clmode| to 'sub'.
407         Equivalent to: >
408                 :ScreenCmdlineConf sub
409 <
410                                                         *:ScreenNoEsc*
411 :ScreenNoEsc            Set |screen_clmode| to 'noesc'.
412         Equivalent to: >
413                 :ScreenCmdlineConf noesc
414
415 ==============================================================================
416
417 8. Bugs and Limitations                                 *screenpaste-bugs*
418
419 Found no way (yet?) to make optional initial [count] argument work with
420 (Normal mode) mappings.
421
422 Screen's copy mechanism treats spaces (including newlines) at the beginning or
423 the end of a selection in a different manner than Vim's visual yank does.
424
425 Screen expands tabs, expect incorrect results if the Screen buffer contains
426 tabs.
427
428 ==============================================================================
429
430 Credits                                                 *screenpaste-credits*
431
432 Mathieu Clabaut, Guo-Peng Wen   let me steal and tweak the inline
433                                 self-install code for this Help document.
434
435 ==============================================================================
436
437  vim:tw=78:ts=8:ft=help:norl: