A consistent mapping scheme for "surrounding" and "leaping"

[ggandor]

Follow-up to the half-baked ideas in #41. I'm just dumping this here, trying to perform inception, so to say.

Q: "Why the fuss at all? Vim is about DIY, everyone can remap everything."

A: Having canonical mappings doesn't mean that everyone should use them. Still, good defaults are very important, especially for plugins like leap or vim-surround, that are kinda special: it's not just specific functionality they provide, for e.g. git stuff or code formatting. They aim to integrate into the very core of Vim as a text editor. Having conventions people - including other plugin authors - can rely on can be a feature too.
And, to be totally honest, because I think I echo many people's sentiments when I say that both should be included in the core eventually, even if that means years from now, even if the "motion" part just means the most bare-bones vanilla 2-char sneaking.

Personally I'd love to be able to break down the status quo with Leap, that is, handle the complete mess that resulted from:

1. tpope holding Vim's native keybindings sacred, and thus coming up with less-than-satisfactory default keybindings (Magic s->S, S->gS transformation when switching from Normal to Visual? ys as the "basic" trigger?).
2. justinmk holding tpope's inconsistent vim-surround keybindings sacred, while overriding the same native keybindings tpope held sacred (s/S/v_s). Thus making 1. irrelevant, and - ironically - 2. itself pointless.

With this out of the way:

Premises:

• s/S are rather useless shortcuts for cl and cc
• gs is needed by no one, there is even a discussion about removing it. IMO, it would make a lot of sense to establish it as a semi-official surround prefix, instead of repurposing it for something else.
• Normal mode "leaping" is more frequent than "surround" operations. We need s/S, sorry.
• Having efficient shortcuts for frequent commands is very important, but consistency matters more than saving a keystroke in all possible situations, as cognitive friction slows you down ultimately.

So here are finalists among the arrangements I came up with:

-----------------------------------------------------------
|     |   surround      |        2-char motion            |
|     |                 |---------------------------------|
|     |                 |  <--  |     -->     | cross-win |  direction
|     |                 |-------|-------------|-----------|
|     |                 | 0 | 2 | -1 | 0 | 1  |    0      |  offset
|     |-----------------|-------|-------------|-----------|
#0 - origins
        vim-surround           vim-sneak
----------------------------------------------------------
|  n  |                 | S     |      s      |           |
|  v  | S(s) gS(s)      | Z     |      s      |           |
|  o* | s(s)  S(s)      | Z     |  z  vz      |           | 
----------------------------------------------------------
#1 - max comfort, less consistent**, less comprehensive (my vote)
                              evil-snipe
-----------------------------------------------------------
|  n  | g(s|S)(gs)(r|d) | S     |      s      |    zS     |
|  v  | g(s|S)          | S   X | x         s |    zS     |
|  o  |                 | S   X | x   vs    s |    zS     |
-----------------------------------------------------------
#2 - less comfort, consistent, comprehensive

-----------------------------------------------------------
|  n  | g(s|S)(gs)(r|d) | S     |      s      |    zS     |
|  v  | g(s|S)          | S   X |  x   s   gx |    zS     |
|  o  |                 | S   X |  x   s   gx |    zS     |
-----------------------------------------------------------
#3 - more comfort, less consistent, less comprehensive
                          ~~lightspeed/leap tweaked a bit
-----------------------------------------------------------
|  n  | g(s|S)(gs)(r|d) | S     |      s      |    zS     |
|  v  | g(s|S)          | S   X |      s    x |    zS     |
|  o  |                 | S   X | vs   s    x |    zS     |
-----------------------------------------------------------

* technically Normal mode mappings, but using y|d|c prefixes
** although feels natural in practice, I have to say, and in the end, this is
  what matters
  
mnemonics:
gs(r|d) ~ "get-surrounding-(replaced|deleted)"
x       ~ "exclusive"
gx      ~ "anti-exclusive", "opposite of x"

surround mappings in detail:

nmap gsd   <Plug>Dsurround
nmap gsr   <Plug>Csurround
nmap gSr   <Plug>CSurround
nmap gs    <Plug>Ysurround
nmap gsgs  <Plug>Yssurround
nmap gS    <Plug>YSurround
nmap gSgS  <Plug>YSsurround
nmap gSgs  <Plug>YSsurround
xmap gs    <Plug>VSurround
xmap gS    <Plug>VgSurround

Alternatives for native keybindings that have been taken over:
s = cl
S = cc
v_s = v_c
v_S = Vc if not already in linewise mode (else = v_c)
v_x = v_d
v_X -> vnoremap D X, and use $D for vanilla v_b_D behav.
gs -> not needed

Observations:

• It can be hard to retrain years of muscle memory (I'm in the same boat), but gsr and gsd are in fact effortless to type; gsiw feels even better than ysiw (y-i is a pretty uncomfortable stretch for the 1st and 2nd finger)! These are actually good sequences.

Musings:

• Would everyone remap zS to something arbitrary but more comfortable anyway, or is it tolerable enough as a default?

[ggandor]

For surround, it would be great to keep the pattern used with native operators, that is, gx, gxx (linewise), gX (some kind of alternative behav.), gXX (linewise gX), v_x, v_X (with v_gx and v_gX as redundant alternatives for the latter). See gu etc.

The problem is, 100% consistency is only possible if we don't use s for Leap at all. But there's simply no other key that is available both in Normal and Visual mode, and is comfortable enough. So I guess we should live with this compromise. (Note that vim-surround does not take over v_s either, to maintain compatibility with Vim's defaults, so we won't make anything worse.)

After taking many factors into consideration, it seems we are left with two choices:

No1
Surround: gz etc. + v_gz (without v_z)
Leap: s/S in all modes (gs for multi-window)

Cons:

• (lack of) surround mnemonic
• surround becomes less comfy, but tolerable

Note: gx surround would work too, but gx is ideal for something like vim-exchange. On this note, couldn't "embox" work as a mnemonic?

No2
Surround: gs etc. + v_gs (without v_s)
Leap: s/S in Normal/Visual, z/Z with operators, zS for multi-window

Cons:

• Leap is not fully consistent (s/S => z/Z in OP mode for no [apparent] reason)
• multi-window needs zS, which is far less comfortable than gs but maybe we can live with that (also, the shape of z is a good mnemonic for "crossing")

---

In the end, both are okay-ish. The choice is:

• (more or less) full consistency for both, 100% comfort for Leap, at the cost of a bit less comfort and no mnemonic for Surround
  OR
• an inconsistent, and slightly less comfortable arrangement for Leap

My main concern is the surround mnemonic. If only we could find an alternative one, like "embrace" ["b"], "box" ["x"], "wrap" ["w"]... but there's nothing for "z".

[nat-418]

Here's what I am using for nvim-surrround:

require('nvim-surround').setup({
  keymaps = {
    insert          = '<C-g>z',
    insert_line     = 'gC-ggZ',
    normal          = 'gz',
    normal_cur      = 'gZ',
    normal_line     = 'gzgz',
    normal_cur_line = 'gZgZ',
    visual          = 'gz',
    visual_line     = 'gZ',
    delete          = 'gzd',
    change          = 'gzc',
  }
})

I think we should find a solution where s is for Leap and z is for "zurround". I think both should be included in Neovim by default, like Matchit and Netrw. Leap is incredible work.

[ggandor]

Yeah, this is what I - in my personal config - have settled on too, except gzz/gZZ instead of duplicating the bigrams, and gzr instead of gzc - to me "replace" sounds more logical than "change".