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

ggandor · 2022-10-07T21:04:02Z

ggandor
Oct 7, 2022
Maintainer

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:

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?).
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 · 2022-10-10T19:38:30Z

ggandor
Oct 10, 2022
Maintainer Author

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".

3 replies

nat-418 Oct 23, 2022

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 Oct 23, 2022
Maintainer Author

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".

seleniy Jan 26, 2025

Thanks for your ideas! I came up with this option:

require("nvim-surround").setup({
  keymaps = {
    insert = "<c-g>x",
    insert_line = "<c-g>X",
    normal = "yx",
    normal_cur = "yxx",
    normal_line = "yX",
    normal_cur_line = "yXX",
    visual = "x",
    visual_line = "X",
    delete = "dx",
    change = "cx",
    change_line = "cX",
  },
})

vim.keymap.set({ "n", "x", "o" }, "s",  "<plug>(leap-forward)")
vim.keymap.set({ "n", "x", "o" }, "S",  "<plug>(leap-backward)")
vim.keymap.set({ "n", "x", "o" }, "gs", "<plug>(leap-from-window)")
vim.keymap.set({ "n", "x", "o" }, "gS", "<plug>(leap)")

(Essentially just replaced all the s with x.)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

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

Uh oh!

Uh oh!

ggandor Oct 7, 2022 Maintainer

Replies: 1 comment · 3 replies

Uh oh!

ggandor Oct 10, 2022 Maintainer Author

Uh oh!

Uh oh!

nat-418 Oct 23, 2022

Uh oh!

ggandor Oct 23, 2022 Maintainer Author

Uh oh!

seleniy Jan 26, 2025

ggandor
Oct 7, 2022
Maintainer

Replies: 1 comment 3 replies

ggandor
Oct 10, 2022
Maintainer Author

ggandor Oct 23, 2022
Maintainer Author