vim-patch:9.1.0058: Cannot map Super Keys in GTK UI (#27204)

Problem:  Cannot map Super Keys in GTK UI
          (Casey Tucker)
Solution: Enable Super Key mappings in GTK using <D-Key>
          (Casey Tucker)

As a developer who works in both Mac and Linux using the same keyboard,
it can be frustrating having to remember different key combinations or
having to rely on system utilities to remap keys.

This change allows `<D-z>` `<D-x>` `<D-c>` `<D-v>` etc. to be recognized
by the `map` commands, along with the `<D-S-...>` shifted variants.

```vimrc
if has('gui_gtk')
	nnoremap  <D-z>    u
	nnoremap  <D-S-Z>  <C-r>
	vnoremap  <D-x>    "+d
	vnoremap  <D-c>    "+y
	cnoremap  <D-v>    <C-R>+
	inoremap  <D-v>    <C-o>"+gP
	nnoremap  <D-v>    "+P
	vnoremap  <D-v>    "-d"+P
	nnoremap  <D-s>    :w<CR>
	inoremap  <D-s>    <C-o>:w<CR>
	nnoremap  <D-w>    :q<CR>
	nnoremap  <D-q>    :qa<CR>
	nnoremap  <D-t>    :tabe<CR>
	nnoremap  <D-S-T>  :vs#<CR><C-w>T
	nnoremap  <D-a>    ggVG
	vnoremap  <D-a>    <ESC>ggVG
	inoremap  <D-a>    <ESC>ggVG
	nnoremap  <D-f>    /
	nnoremap  <D-g>    n
	nnoremap  <D-S-G>  N
	vnoremap  <D-x>    "+x
endif
```

closes: vim/vim#12698

https://github.com/vim/vim/commit/92e90a1e102825aa9149262cacfc991264db05df

Co-authored-by: Casey Tucker <dctucker@hotmail.com>

5 files changed, 29 insertions, 4 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 9750031efd..ce12437c25 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -2270,7 +2270,7 @@ getcharmod()                                                      *getcharmod()*
 			32	mouse double click
 			64	mouse triple click
 			96	mouse quadruple click (== 32 + 64)
-			128	command (Macintosh only)
+			128	command (Mac) or super
 		Only the modifiers that have not been included in the
 		character itself are obtained.  Thus Shift-a results in "A"
 		without a modifier.  Returns 0 if no modifiers are used.
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index d1f61dce85..68206dd494 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -849,8 +849,15 @@ For the Meta modifier the "T" character is used.  For example, to map Meta-b
 in Insert mode: >
 	:imap <T-b> terrible
 
+1.12 MAPPING SUPER-KEYS or COMMAND-KEYS		*:map-super-keys* *:map-cmd-key*
 
-1.12 MAPPING AN OPERATOR				*:map-operator*
+The Super / Command modifier is available if the terminal or GUI supports it.
+The character "D" is used for the Super / Command modifier.
+
+For example, to map Command-b in Insert mode: >
+	:imap <D-b> barritone
+
+1.13 MAPPING AN OPERATOR				*:map-operator*
 
 An operator is used before a {motion} command.  To define your own operator
 you must create a mapping that first sets the 'operatorfunc' option and then
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 7f5860c3a3..2280eec5c8 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -2777,7 +2777,7 @@ function vim.fn.getchar() end
 ---   32  mouse double click
 ---   64  mouse triple click
 ---   96  mouse quadruple click (== 32 + 64)
----   128  command (Macintosh only)
+---   128  command (Mac) or super
 --- Only the modifiers that have not been included in the
 --- character itself are obtained.  Thus Shift-a results in "A"
 --- without a modifier.  Returns 0 if no modifiers are used.
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 22c208426c..9f50fd1758 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -3461,7 +3461,7 @@ M.funcs = {
       	32	mouse double click
       	64	mouse triple click
       	96	mouse quadruple click (== 32 + 64)
-      	128	command (Macintosh only)
+      	128	command (Mac) or super
       Only the modifiers that have not been included in the
       character itself are obtained.  Thus Shift-a results in "A"
       without a modifier.  Returns 0 if no modifiers are used.
diff --git a/test/old/testdir/test_mapping.vim b/test/old/testdir/test_mapping.vim
index 36a46684c1..a5bf1a0602 100644
--- a/test/old/testdir/test_mapping.vim
+++ b/test/old/testdir/test_mapping.vim
@@ -235,6 +235,24 @@ func Test_map_meta_multibyte()
   iunmap <M-á>
 endfunc
 
+func Test_map_super_quotes()
+  if has('gui_gtk') || has('gui_gtk3') || has("macos")
+    imap <D-"> foo
+    call feedkeys("Go-\<*D-\">-\<Esc>", "xt")
+    call assert_equal("-foo-", getline('$'))
+    set nomodified
+    iunmap <D-">
+  endif
+endfunc
+
+func Test_map_super_multibyte()
+  if has('gui_gtk') || has('gui_gtk3') || has("macos")
+    imap <D-á> foo
+    call assert_match('i  <D-á>\s*foo', execute('imap'))
+    iunmap <D-á>
+  endif
+endfunc
+
 func Test_abbr_after_line_join()
   new
   abbr foo bar