Merge pull request #34244 from brianhuster/vim-6fea0a5

vim-patch: document on how to write lang annotation for codeblock in help file

runtime/doc/helphelp.txt

@@ -373,11 +373,17 @@ To quote a block of ex-commands verbatim, place a greater than (>) character
 at the end of the line before the block and a less than (<) character as the
 first non-blank on a line following the block.  Any line starting in column 1
 also implicitly stops the block of ex-commands before it.  E.g. >
-    function Example_Func()
-	echo "Example"
-    endfunction
+	function Example_Func()
+	  echo "Example"
+	endfunction
 <
-
+To enable syntax highlighting for a block of code, place a language name
+annotation (e.g. "vim") after a greater than (>) character.  E.g. >vim
+	function Example_Func()
+	  echo "Example"
+	endfunction
+<
+						*help-notation*
 The following are highlighted differently in a Vim help file:
   - a special key name expressed either in <> notation as in <PageDown>, or
     as a Ctrl character as in CTRL-X

runtime/syntax/help.vim

@@ -1,7 +1,7 @@
 " Vim syntax file
 " Language:	Vim help file
 " Maintainer:	The Vim Project <https://github.com/vim/vim>
-" Last Change:	2024 Oct 16
+" Last Change:	2024 Dec 15
 " Former Maintainer:	Bram Moolenaar <Bram@vim.org>
 
 " Quit when a (custom) syntax file was already loaded
@@ -12,15 +12,36 @@ endif
 let s:cpo_save = &cpo
 set cpo&vim
 
+if !exists('g:help_example_languages')
+  let g:help_example_languages = #{ vim: 'vim' }
+endif
+
 syn match helpHeadline		"^[A-Z.][-A-Z0-9 .,()_']*?\=\ze\(\s\+\*\|$\)"
 syn match helpSectionDelim	"^===.*===$"
 syn match helpSectionDelim	"^---.*--$"
-" Nvim: support language annotation in codeblocks
+
 if has("conceal")
-  syn region helpExample	matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^>[a-z0-9]*$" end="^[^ \t]"me=e-1 end="^<" concealends
+  syn region helpExample	matchgroup=helpIgnore
+        \ start="\%(^\| \)>[a-z0-9]*$" end="^[^ \t]"me=e-1 end="^<" concealends
 else
-  syn region helpExample	matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^>[a-z0-9]*$" end="^[^ \t]"me=e-1 end="^<"
+   syn region helpExample	matchgroup=helpIgnore
+         \ start="\%(^\| \)>[a-z0-9]*$" end="^[^ \t]"me=e-1 end="^<"
 endif
+
+for [s:lang, s:syntax] in g:help_example_languages->items()
+  unlet! b:current_syntax
+  " silent! to prevent E403
+  execute 'silent! syn include' $'@helpExampleHighlight_{s:lang}'
+        \ $'syntax/{s:syntax}.vim'
+
+  execute $'syn region helpExampleHighlight_{s:lang} matchgroup=helpIgnore'
+        \ $'start=/\%(^\| \)>{s:lang}$/'
+        \ 'end=/^[^ \t]/me=e-1 end=/^</'
+        \ (has("conceal") ? 'concealends' : '')
+        \ $'contains=@helpExampleHighlight_{s:lang} keepend'
+endfor
+unlet! s:lang s:syntax
+
 syn match helpHyperTextJump	"\\\@<!|[#-)!+-~]\+|" contains=helpBar
 syn match helpHyperTextEntry	"\*[#-)!+-~]\+\*\s"he=e-1 contains=helpStar
 syn match helpHyperTextEntry	"\*[#-)!+-~]\+\*$" contains=helpStar