fix(help): handle escape edge cases #40901

* fix(help): preserve multi-letter CTRL modifiers in :help subject

Problem: After PR 39537 normalized `CTRL-U-default` by excluding
`-` from the trigger char class, the regex `(CTRL%-[^{])([^-_\\])`
also fires between `CTRL-S` and the `H` of the `SHIFT` modifier
in tags like `c_CTRL-SHIFT-V`, splitting it into the non-existent
`c_CTRL-S_HIFT-V`.

Solution: Exclude uppercase letters from the char class so a
multi-letter modifier following `CTRL-X` (e.g. `SHIFT`, `ALT`) is
no longer split. The `-` exclusion from 39537 is preserved so
`i_CTRL-U-default` still works.

* fix(help): escape ~ in expr-=~? exception to keep regex valid

Problem: The `expr-=~?` exception in the tag alias table maps to
`=~?`, but in Vim's regex engine `~` refers to the previous
substitute pattern. With no prior substitute the pattern fails to
compile, so `:help expr-=~?` returns E149 even though the tag exists.

Solution: Escape `~` as \\\~` so the alias expands to a valid
regex (`=\\\~?`) that substring-matches the `expr-=~?` tag. Other
`expr-X?` entries are unaffected since they don't contain `~`.

* fix(help): don't insert _ before CTRL- when preceded by -

Problem: The rule `([^_])CTRL%- -> %1_CTRL-` inserts an underscore
between any non-underscore char and `CTRL-`, which wrongly rewrites
tags like `map-CTRL-C` and `telnet-CTRL-]` (where `CTRL-` is
literal text in the tag, not a key chord).

Solution: Exclude `-` from the trigger char class so a hyphen
immediately before `CTRL-` is preserved. The existing behavior for
`iCTRL-GCTRL-J` -> `i_CTRL-G_CTRL-J` is unaffected because the
`G` before `CTRL-J` is not `-`.

* fix(help): only treat ^X as caret notation for valid control chars

Problem: The regex `%^([^_])` converts any `^X` to `CTRL-X`,
including `:set^=` where `^=` is literal text in the tag, not a
caret-notation control character.

Solution: Restrict the transformation to caret-notation chars
(`%a` or one of `?@[\\]^{}`). This matches the C reference
behavior where `^X` is only converted when X is alphanumeric or one
of the control-notation punctuation chars. `{` is retained so
`^{char}` still maps to the `CTRL-{char}` placeholder tag.

1 files changed, 8 insertions, 4 deletions

diff --git a/runtime/lua/vim/_core/help.lua b/runtime/lua/vim/_core/help.lua
index cc410daf17..0dad8f93ff 100644
--- a/runtime/lua/vim/_core/help.lua
+++ b/runtime/lua/vim/_core/help.lua
@@ -39,7 +39,7 @@ local tag_exceptions = {
   ['expr-<=?'] = '<=?',
   ['expr-<?'] = '<?',
   ['expr-==?'] = '==?',
-  ['expr-=~?'] = '=~?',
+  ['expr-=~?'] = '=\\~?',
   ['expr->=?'] = '>=?',
   ['expr->?'] = '>?',
   ['expr-is?'] = 'is?',
@@ -103,12 +103,16 @@ function M.escape_subject(word)
 
     -- Change caret notation to 'CTRL-', except '^_'
     -- E.g. 'i^G^J' --> 'iCTRL-GCTRL-J'
-    word = word:gsub('%^([^_])', 'CTRL-%1')
+    -- Only treat '^' as control notation when followed by a caret-notation
+    -- char (a letter or one of "?@[\]^{"); otherwise leave it literal so
+    -- patterns like ':set^=' are not wrongly split. '{' is included so
+    -- '^{char}' matches the 'CTRL-{char}' placeholder tag.
+    word = word:gsub('%^([%a?@\\[\\%]{^])', 'CTRL-%1')
     -- Add underscores around 'CTRL-X' characters
     -- E.g. 'iCTRL-GCTRL-J' --> 'i_CTRL-G_CTRL-J'
     -- Only exception: 'CTRL-{character}'
-    word = word:gsub('([^_])CTRL%-', '%1_CTRL-')
-    word = word:gsub('(CTRL%-[^{])([^-_\\])', '%1_%2')
+    word = word:gsub('([^-_])CTRL%-', '%1_CTRL-')
+    word = word:gsub('(CTRL%-[^{])([^%u_\\-])', '%1_%2')
 
     -- Skip function arguments
     -- E.g. 'abs({expr})' --> 'abs'