runtime(vim): Update help syntax file, improve highlighting of included Vim examples

- Take over as file maintainer.
- Improve highlighting of legacy script examples by using :syn-iskeyword
  with the default 'iskeyword' value. Vim9 script examples are not
  supported yet.
- Match admonition labels in more contexts.
- Match URLs in more contexts.

fixes #17721
closes: #17731

Signed-off-by: Doug Kearns <dougkearns@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

.github/MAINTAINERS

@@ -510,6 +510,7 @@ runtime/syntax/hare.vim					@selenebun
 runtime/syntax/haredoc.vim				@selenebun
 runtime/syntax/haskell.vim				@coot
 runtime/syntax/hcl.vim					@gpanders
+runtime/syntax/help.vim					@dkearns
 runtime/syntax/help_ru.vim				@RestorerZ
 runtime/syntax/hgcommit.vim				@k-takata
 runtime/syntax/hitest.vim				@lacygoill

runtime/doc/eval.txt

@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 9.1.  Last change: 2025 Jun 28
+*eval.txt*	For Vim version 9.1.  Last change: 2025 Jul 13
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -5210,7 +5210,7 @@ The |:Launch| user command uses shell completion for its first argument.
 
 NOTE: escaping of <args> is left to the user
 
-Examples: >vim
+Examples: >
 	vim9script
 
 	import autoload 'dist/vim9.vim'

runtime/doc/fold.txt

@@ -1,4 +1,4 @@
-*fold.txt*      For Vim version 9.1.  Last change: 2025 Jul 09
+*fold.txt*      For Vim version 9.1.  Last change: 2025 Jul 13
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -164,7 +164,7 @@ level is found.
 If this proves difficult, the next best thing could be to cache all fold
 levels in a buffer-local variable (b:foldlevels) that is only updated on
 |b:changedtick|:
->vim
+>
   vim9script
   def MyFoldFunc(): number
     if b:lasttick == b:changedtick

runtime/doc/usr_25.txt

@@ -1,4 +1,4 @@
-*usr_25.txt*	For Vim version 9.1.  Last change: 2025 Jun 10
+*usr_25.txt*	For Vim version 9.1.  Last change: 2025 Jun 13
 
 		     VIM USER MANUAL - by Bram Moolenaar
 
@@ -200,7 +200,7 @@ command: >vim
 
 Or put this line in your |vimrc|: >vim
 
-	packadd! justify
+	:packadd! justify
 
 This Vim script file defines a new visual command "_j".  To justify a block of
 text, highlight the text in Visual mode and then execute "_j".

runtime/syntax/help.vim

@@ -1,7 +1,7 @@
 " Vim syntax file
-" Language:	Vim help file
+" Language:		Vim help file
-" Maintainer:	The Vim Project <https://github.com/vim/vim>
+" Maintainer:		Doug Kearns <dougkearns@gmail.com>
-" Last Change:	2024 Dec 25
+" Last Change:		2025 Jul 12
 " Former Maintainer:	Bram Moolenaar <Bram@vim.org>
 
 " Quit when a (custom) syntax file was already loaded
@@ -12,6 +12,8 @@ endif
 let s:cpo_save = &cpo
 set cpo&vim
 
+syn iskeyword @,48-57,_,192-255
+
 if !exists('g:help_example_languages')
   let g:help_example_languages = #{ vim: 'vim' }
 endif
@@ -78,24 +80,32 @@ if has("conceal")
 else
   syn match helpIgnore		"." contained
 endif
-syn keyword helpNote		note Note NOTE note: Note: NOTE: Notes Notes:
-syn match helpNote		"\c(note\(:\|\>\)"ms=s+1
-syn keyword helpWarning		WARNING WARNING: Warning:
-syn keyword helpDeprecated	DEPRECATED DEPRECATED: Deprecated:
-syn match helpSpecial		"\<N\>"
-syn match helpSpecial		"\<N\.$"me=e-1
-syn match helpSpecial		"\<N\.\s"me=e-2
-syn match helpSpecial		"(N\>"ms=s+1
 
+" match 'iskeyword' word boundaries, '!-~,^*,^|,^",192-255'
+let s:iskeyword =  '!#-)+-{}~\d192-\d255'
+let s:start_word = $'\%(^\|[^{s:iskeyword}]\)\@1<='
+let s:end_word =      $'\%([^{s:iskeyword}]\|$\)\@='
+
+exec $'syn match helpNote	"{s:start_word}\%(note\|Note\|NOTE\|Notes\):\={s:end_word}"'
+exec $'syn match helpNote       "\c[[(]note\%(:\|{s:end_word}\)"ms=s+1'
+exec $'syn match helpWarning	"{s:start_word}\%(WARNING:\=\|Warning:\){s:end_word}"'
+exec $'syn match helpDeprecated	"{s:start_word}\%(DEPRECATED:\=\|Deprecated:\){s:end_word}"'
+exec $'syn match helpSpecial	"{s:start_word}N{s:end_word}"'
+exec $'syn match helpSpecial	"{s:start_word}N\.$"me=e-1'
+exec $'syn match helpSpecial	"{s:start_word}N\.\s"me=e-2'
+exec $'syn match helpSpecial	"(N{s:end_word}"ms=s+1'
 syn match helpSpecial		"\[N]"
 " avoid highlighting N  N in quickref.txt
 syn match helpSpecial		"N  N"he=s+1
 syn match helpSpecial		"Nth"me=e-2
 syn match helpSpecial		"N-1"me=e-2
 " highlighting N for :resize in windows.txt
-syn match helpSpecial		"] -N\>"ms=s+3
+exec $'syn match helpSpecial	"] -N{s:end_word}"ms=s+3'
-syn match helpSpecial		"+N\>"ms=s+1
+exec $'syn match helpSpecial	"+N{s:end_word}"ms=s+1'
-syn match helpSpecial		"\[+-]N\>"ms=s+4
+exec $'syn match helpSpecial	"\[+-]N{s:end_word}"ms=s+4'
+
+unlet s:iskeyword s:start_word s:end_word
+
 " highlighting N of cinoptions-values in indent.txt
 syn match helpSpecial		"^\t-\?\zsNs\?\s"me=s+1
 " highlighting N of cinoptions-values in indent.txt
@@ -183,6 +193,7 @@ let s:i = match(expand("%"), '\.\a\ax$')
 if s:i > 0
   exe "runtime syntax/help_" . strpart(expand("%"), s:i + 1, 2) . ".vim"
 endif
+unlet s:i
 
 syn sync minlines=40
 

runtime/syntax/testdir/dumps/help_00.dump

@@ -0,0 +1,20 @@
+>V+0#af5f00255#ffffff0|I|M| |H|E|L|P| |F|I|L|E| |F|O|R|M|A|T| +0#0000000&@54
+@75
+@75
+|I+0#e000e06&|s@1|u|e| |#|1|7@1|2|1| |(|S|t|r|a|n|g|e| |>|v|i|m| |h|i|g|h|l|i|g|h|t|i|n|g| |i|n| |h|e|l|p| |d|o|c|u|m|e|n|t|a|t|i|o|n|?|)|~+0#ffffff16&| +0#0000000&@10
+@75
+@32|*+0#ffffff16&|r+0#e000002&|e|s|t|o|r|e|-|c|u|r|s|o|r|*+0#ffffff16&| +0#0000000&|*+0#ffffff16&|l+0#e000002&|a|s|t|-|p|o|s|i|t|i|o|n|-|j|u|m|p|*+0#ffffff16&| +0#0000000&| +0#ffffff16&|>|v|i|m
+| +0#0000000&@3|a+0#af5f00255&|u|g|r|o|u|p| +0#0000000&|R|e|s|t|o|r|e|C|u|r|s|o|r| @49
+@6|a+0#af5f00255&|u|t|o|c|m|d|!| +0#0000000&@60
+@6|a+0#af5f00255&|u|t|o|c|m|d| +0#0000000&|B+0#00e0003&|u|f|R|e|a|d|P|o|s|t| +0#0000000&|*+0#e000e06&| +0#0000000&@47
+@8|\+0#e000e06&| +0#0000000&|l+0#af5f00255&|e|t| +0#0000000&|l|i|n|e| |=+0#af5f00255&| +0#0000000&|l+0#00e0e07&|i|n|e|(+0#e000e06&|"+0#e000002&|'|\+0#e000e06&|"|"+0#e000002&|)+0#e000e06&| +0#0000000&@42
+@8|\+0#e000e06&| +0#0000000&||| |i+0#af5f00255&|f| +0#0000000&|l|i|n|e| |>+0#af5f00255&|=| +0#0000000&|1+0#e000002&| +0#0000000&|&+0#af5f00255&@1| +0#0000000&|l|i|n|e| |<+0#af5f00255&|=| +0#0000000&|l+0#00e0e07&|i|n|e|(+0#e000e06&|"+0#e000002&|$|"|)+0#e000e06&| +0#0000000&|&+0#af5f00255&@1| +0#0000000&|&+0#00e0e07&|f|i|l|e|t|y|p|e| +0#0000000&|!+0#af5f00255&|~|#| +0#0000000&|'+0#e000002&|c|o|m@1|i|t|'| +0#0000000&@3
+@8|\+0#e000e06&| +0#0000000&@5|&+0#af5f00255&@1| +0#0000000&|i+0#00e0e07&|n|d|e|x|(+0#e000e06&|[|'+0#e000002&|x@1|d|'|,+0#0000000&| |'+0#e000002&|g|i|t|r|e|b|a|s|e|'|]+0#e000e06&|,+0#0000000&| |&+0#00e0e07&|f|i|l|e|t|y|p|e|)+0#e000e06&| +0#0000000&|=+0#af5f00255&@1| +0#0000000&|-+0#af5f00255&|1+0#e000002&| +0#0000000&@12
+@8|\+0#e000e06&| +0#0000000&@5|&+0#af5f00255&@1| +0#0000000&|!+0#af5f00255&|&+0#00e0e07&|d|i|f@1| +0#0000000&@50
+@8|\+0#e000e06&| +0#0000000&||| @2|e+0#af5f00255&|x|e|c|u|t|e| +0#0000000&|"+0#e000002&|n|o|r|m|a|l|!| |g|`|\+0#e000e06&|"|"+0#e000002&| +0#0000000&@38
+@8|\+0#e000e06&| +0#0000000&||| |e+0#af5f00255&|n|d|i|f| +0#0000000&@57
+@4|a+0#af5f00255&|u|g|r|o|u|p| +0#0000000&|E|N|D| @59
+@75
+@75
+|U+0#e000e06&|R|L|s|~+0#ffffff16&| +0#0000000&@69
+@57|1|,|1| @10|T|o|p| 

runtime/syntax/testdir/dumps/help_01.dump

@@ -0,0 +1,20 @@
+| +0&#ffffff0@7|\+0#e000e06&| +0#0000000&||| @2|e+0#af5f00255&|x|e|c|u|t|e| +0#0000000&|"+0#e000002&|n|o|r|m|a|l|!| |g|`|\+0#e000e06&|"|"+0#e000002&| +0#0000000&@38
+@8|\+0#e000e06&| +0#0000000&||| |e+0#af5f00255&|n|d|i|f| +0#0000000&@57
+@4|a+0#af5f00255&|u|g|r|o|u|p| +0#0000000&|E|N|D| @59
+@75
+@75
+>U+0#e000e06&|R|L|s|~+0#ffffff16&| +0#0000000&@69
+@75
+@48|*+0#ffffff16&|g+0#e000002&|:|z|i|g|_|r|e|c|o|m@1|e|n|d|e|d|_|s|t|y|l|e|*+0#ffffff16&| +0#0000000&@1
+|B|y| |d|e|f|a|u|l|t| |t|h|e| |f|o|l@1|o|w|i|n|g| |i|n|d|e|n|t|a|t|i|o|n| |o|p|t|i|o|n|s| |a|r|e| |s|e|t|,| |i|n| |a|c@1|o|r|d|a|n|c|e| |w|i|t|h| |Z|i
+|g|'|s| @71
+|r|e|c|o|m@1|e|n|d|e|d| |s|t|y|l|e| |(|h+0#e000002&|t@1|p|s|:|/@1|z|i|g|l|a|n|g|.|o|r|g|/|d|o|c|u|m|e|n|t|a|t|i|o|n|/|m|a|s|t|e|r|/|)+0#0000000&|:| +0#ffffff16&|>| +0#0000000&@10
+@75
+@75
+|N+0#e000e06&|O|T|E|,| |W|A|R|N|I|N|G| |a|n|d| |D|E|P|R|E|C|A|T|E|D|~+0#ffffff16&| +0#0000000&@45
+@75
+|W|h|e|n| |y|o|u| |'|s|e|n|d| |a| |f|i|l|e| |t|o| |V|i|m|'|,| |V|i|m| |c|h|a|n|g|e|s| |t|o| |t|h|a|t| |f|i|l|e|'|s| |d|i|r|e|c|t|o|r|y|.| @1|N|o|t|e|,
+|h|o|w|e|v|e|r|,| |t|h|a|t| |a|n|y| |l|o|n|g| |d|i|r|e|c|t|o|r|y| |n|a|m|e|s| |w|i|l@1| |a|p@1|e|a|r| |i|n| |t|h|e|i|r| |s|h|o|r|t| |(|M|S|-|D|O|S|)| 
+|f|o|r|m| |o|n| |s|o|m|e| |W|i|n|d|o|w|s| |v|e|r|s|i|o|n|s|.| @1|T|h|i|s| |i|s| |a| |l|i|m|i|t|a|t|i|o|n| |o|f| |t|h|e| |W|i|n|d|o|w|s| |"|S|e|n|d| |T
+|o|"| @72
+@57|1|9|,|1| @9|8|1|%| 

runtime/syntax/testdir/dumps/help_02.dump

@@ -0,0 +1,20 @@
+|f+0&#ffffff0|o|r|m| |o|n| |s|o|m|e| |W|i|n|d|o|w|s| |v|e|r|s|i|o|n|s|.| @1|T|h|i|s| |i|s| |a| |l|i|m|i|t|a|t|i|o|n| |o|f| |t|h|e| |W|i|n|d|o|w|s| |"|S|e|n|d| |T
+|o|"| @72
+|m|e|c|h|a|n|i|s|m|.| @64
+@75
+>v|i|m|:| |s|e|t| |f|t|=|h|e|l|p|:| @57
+|~+0#4040ff13&| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+|~| @73
+| +0#0000000&@56|3@1|,|1| @9|B|o|t| 

runtime/syntax/testdir/input/help.txt

@@ -0,0 +1,33 @@
+VIM HELP FILE FORMAT
+
+
+Issue #17721 (Strange >vim highlighting in help documentation?)~
+
+				*restore-cursor* *last-position-jump*  >vim
+    augroup RestoreCursor
+      autocmd!
+      autocmd BufReadPost *
+        \ let line = line("'\"")
+        \ | if line >= 1 && line <= line("$") && &filetype !~# 'commit'
+        \      && index(['xxd', 'gitrebase'], &filetype) == -1
+        \      && !&diff
+        \ |   execute "normal! g`\""
+        \ | endif
+    augroup END
+
+
+URLs~
+
+						*g:zig_recommended_style*
+By default the following indentation options are set, in accordance with Zig's
+recommended style (https://ziglang.org/documentation/master/): >
+
+
+NOTE, WARNING and DEPRECATED~
+
+When you 'send a file to Vim', Vim changes to that file's directory.  Note,
+however, that any long directory names will appear in their short (MS-DOS)
+form on some Windows versions.  This is a limitation of the Windows "Send To"
+mechanism.
+
+vim: set ft=help: