Begin phasing out vs and introduce vgS

doc/surround.txt

@@ -66,22 +66,26 @@ There is also *yS* and *ySS* which indent the surrounded text and place it
 on a line of its own.
 
 In visual mode, a simple "s" with an argument wraps the selection.  This is
-referred to as the *vs* mapping, although ordinarily there will be
+referred to as the *vS* mapping, although ordinarily there will be
 additional keystrokes between the v and s.  In linewise visual mode, the
-surroundings are placed on separate lines.  In blockwise visual mode, each
+surroundings are placed on separate lines and indented.  In blockwise visual
-line is surrounded.
+mode, each line is surrounded.
 
-An "S" in visual mode (*vS*) behaves similarly but always places the
+A "gS" in visual mode, known as *vgS* , behaves similarly.  In linewise visual
-surroundings on separate lines.  Additionally, the surrounded text is
+mode, the automatic indenting is surpressed.  In blockwise visual mode, this
-indented.  In blockwise visual mode, using "S" instead of "s" instead skips
+enables surrounding past the end of the like with 'virtualedit' set (there
-trailing whitespace.
+seems to be no way in Vim Script to differentiate between a jagged end of line
+selection and a virtual block selected past the end of the line, so two maps
+were needed).
 
-Note that "s" and "S" already have valid meaning in visual mode, but it is
+Additionally, there is a legacy "s" or *vs* mapping which is basically the
-identical to "c".  If you have muscle memory for "s" and would like to use a
+same as |vS|.  Due to popular demand of wanting to use "s" as Vim does to mean
-different key, add your own mapping and the existing one will be disabled.
+replacing the selection (also available as "c"), this mapping is going away.
+If you were one of these people and would like to disable "s" with the current
+release, indicate this to surround.vim by assigning the "s" mapping to
+something else.
 >
-  vmap <Leader>s <Plug>Vsurround
+  xmap <Leader>s <Plug>Vsurround
-  vmap <Leader>S <Plug>VSurround
 <
                                                 *i_CTRL-G_s* *i_CTRL-G_S*
 Finally, there is an experimental insert mode mapping on <C-G>s and <C-S>.

plugin/surround.vim

@@ -302,7 +302,7 @@ function! s:wrap(string,char,type,...)
     " Really we should be iterating over the buffer
     let repl = substitute(before,'[\\~]','\\&','g').'\1'.substitute(after,'[\\~]','\\&','g')
     let repl = substitute(repl,'\n',' ','g')
-    let keeper = substitute(keeper."\n",'\(.\{-\}\)\('.(special ? '\s\{-\}' : '').'\n\)',repl.'\n','g')
+    let keeper = substitute(keeper."\n",'\(.\{-\}\)\(\n\)',repl.'\n','g')
     let keeper = substitute(keeper,'\n\%$','','')
   else
     let keeper = before.extraspace.keeper.extraspace.after
@@ -512,7 +512,9 @@ function! s:opfunc(type,...) " {{{1
     let type = 'V'
   elseif a:type ==# "v" || a:type ==# "V" || a:type ==# "\<C-V>"
     let ve = &virtualedit
+    if !(a:0 && a:1)
       set virtualedit=
+    endif
     silent exe 'norm! gv"'.reg.'y'
     let &virtualedit = ve
   elseif a:type =~ '^\d\+$'
@@ -533,7 +535,7 @@ function! s:opfunc(type,...) " {{{1
     let keeper = substitute(keeper,'\_s\@<!\s*$','','')
   endif
   call setreg(reg,keeper,type)
-  call s:wrapreg(reg,char,a:0)
+  call s:wrapreg(reg,char,a:0 && a:1)
   if type ==# "v" && a:type !=# "v" && append != ""
     call setreg(reg,append,"ac")
   endif
@@ -545,7 +547,7 @@ function! s:opfunc(type,...) " {{{1
   let &selection = sel_save
   let &clipboard = cb_save
   if a:type =~ '^\d\+$'
-    silent! call repeat#set("\<Plug>Y".(a:0 ? "S" : "s")."surround".char,a:type)
+    silent! call repeat#set("\<Plug>Y".(a:0 && a:1 ? "S" : "s")."surround".char,a:type)
   endif
 endfunction
 
@@ -577,7 +579,8 @@ nnoremap <silent> <Plug>YSsurround :<C-U>call <SID>opfunc2(v:count1)<CR>
 nnoremap <silent> <Plug>Ysurround  :<C-U>set opfunc=<SID>opfunc<CR>g@
 nnoremap <silent> <Plug>YSurround  :<C-U>set opfunc=<SID>opfunc2<CR>g@
 vnoremap <silent> <Plug>Vsurround  :<C-U>call <SID>opfunc(visualmode())<CR>
-vnoremap <silent> <Plug>VSurround  :<C-U>call <SID>opfunc2(visualmode())<CR>
+vnoremap <silent> <Plug>VSurround  :<C-U>call <SID>opfunc(visualmode(),visualmode() ==# 'V' ? 1 : 0)<CR>
+vnoremap <silent> <Plug>VgSurround :<C-U>call <SID>opfunc(visualmode(),visualmode() ==# 'V' ? 0 : 1)<CR>
 inoremap <silent> <Plug>Isurround  <C-R>=<SID>insert()<CR>
 inoremap <silent> <Plug>ISurround  <C-R>=<SID>insert(1)<CR>
 
@@ -589,7 +592,7 @@ if !exists("g:surround_no_mappings") || ! g:surround_no_mappings
   nmap      yss  <Plug>Yssurround
   nmap      ySs  <Plug>YSsurround
   nmap      ySS  <Plug>YSsurround
-  if !hasmapto("<Plug>Vsurround","v")
+  if !hasmapto("<Plug>Vsurround","v") && !hasmapto("<Plug>VSurround","v")
     if exists(":xmap")
       xmap  s    <Plug>Vsurround
     else
@@ -603,6 +606,7 @@ if !exists("g:surround_no_mappings") || ! g:surround_no_mappings
       vmap  S    <Plug>VSurround
     endif
   endif
+  vmap      gS   <Plug>VgSurround
   if !hasmapto("<Plug>Isurround","i") && "" == mapcheck("<C-S>","i")
     imap    <C-S> <Plug>Isurround
   endif