runtime(help): Add better support for language annotation highlighting

closes: #16238

Co-authored-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: h_east <h.east.727@gmail.com>
Signed-off-by: Shougo Matsushita <Shougo.Matsu@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

runtime/doc/helphelp.txt

@@ -1,4 +1,4 @@
-*helphelp.txt*	For Vim version 9.1.  Last change: 2024 Dec 15
+*helphelp.txt*	For Vim version 9.1.  Last change: 2024 Dec 25
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -433,17 +433,38 @@ 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
 <
-It's possible to add Vim syntax highlighting support to code examples.  This
-can be done by adding "vim" after the greater than (>) character (">vim").
+
+To add annotation in the block, place the annotation (ex: "lua") after a
+greater than (>) character.  E.g: >lua
+	print("hello")
+<
+Note: uses lua syntax highlighting, if "lua" key is in
+|g:help_example_languages|.
+
+It's possible to add Vim syntax highlighting support to code examples.
 E.g: >vim
-    function Example_Func()
-	echo "Example"
-    endfunction
+	function Example_Func()
+	  echo "Example"
+	endfunction
 <
+						*g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+	:let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key represents the annotation marker name, and the value is the 'syntax'
+name.  By default, help files support only Vim script highlighting.
+Note: When setting "g:help_example_languages", if you do not include "vim"
+key, the Vim syntax highlighting will not be enabled. If you set it to an
+empty value, syntax highlighting for embedded languages will be disabled.
+
+Further note: including additional syntax languages into help files may not
+always work perfectly, if the included 'syntax' script does not account for
+such an import.
+						*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/doc/os_dos.txt

@@ -1,4 +1,4 @@
-*os_dos.txt*    For Vim version 9.1.  Last change: 2024 Sep 24
+*os_dos.txt*    For Vim version 9.1.  Last change: 2024 Dec 25
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -292,9 +292,9 @@ should be:
 'shellquote'	   "
 'shellxquote'						 "
 
-For Dos 16 bit this starts the shell as:
+For Dos 16 bit this starts the shell as: >
 	<shell> -c "command name" >file
-For Win32 as:
+For Win32 as: >
 	<shell> -c "command name >file"
 For DOS 32 bit, DJGPP does this internally somehow.
 

runtime/doc/tags

@@ -7583,6 +7583,7 @@ g:gzip_exec	pi_gzip.txt	/*g:gzip_exec*
 g:hare_recommended_style	ft_hare.txt	/*g:hare_recommended_style*
 g:hare_space_error	ft_hare.txt	/*g:hare_space_error*
 g:haredoc_search_depth	ft_hare.txt	/*g:haredoc_search_depth*
+g:help_example_languages	helphelp.txt	/*g:help_example_languages*
 g:html_charset_override	syntax.txt	/*g:html_charset_override*
 g:html_diff_one_file	syntax.txt	/*g:html_diff_one_file*
 g:html_dynamic_folds	syntax.txt	/*g:html_dynamic_folds*
@@ -8086,6 +8087,7 @@ help-TOC	helphelp.txt	/*help-TOC*
 help-buffer-options	helphelp.txt	/*help-buffer-options*
 help-context	help.txt	/*help-context*
 help-curwin	tips.txt	/*help-curwin*
+help-notation	helphelp.txt	/*help-notation*
 help-summary	usr_02.txt	/*help-summary*
 help-tags	tags	1
 help-toc-install	helphelp.txt	/*help-toc-install*

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 Dec 15
+" Last Change:	2024 Dec 25
 " Former Maintainer:	Bram Moolenaar <Bram@vim.org>
 
 " Quit when a (custom) syntax file was already loaded
@@ -12,26 +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	"^---.*--$"
 
-unlet! b:current_syntax
-" sil! to prevent E403
-silent! syntax include @VimScript syntax/vim.vim
 if has("conceal")
-  syn region helpExample	matchgroup=helpIgnore start=" >$" start="^>$" end="^[^ \t]"me=e-1 end="^<" concealends
-  syn region helpExampleVimScript matchgroup=helpIgnore
-        \ start=/^>vim$/ start=/ >vim$/
-        \ end=/^[^ \t]/me=e-1 end=/^</ concealends
-        \ contains=@VimScript keepend
+  syn region helpExample	matchgroup=helpIgnore
+        \ start="\%(^\| \)>[a-z0-9]*$" end="^[^ \t]"me=e-1 end="^<" concealends
  else
-   syn region helpExample	matchgroup=helpIgnore start=" >$" start="^>$" end="^[^ \t]"me=e-1 end="^<"
-   syn region helpExampleVimScript matchgroup=helpIgnore
-         \ start=/^>vim$/ start=/ >vim$/
-         \ end=/^[^ \t]/me=e-1 end=/^</
-         \ contains=@VimScript keepend
+   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
+
 if has("ebcdic")
   syn match helpHyperTextJump	"\\\@<!|[^"*|]\+|" contains=helpBar
   syn match helpHyperTextEntry	"\*[^"*|]\+\*\s"he=e-1 contains=helpStar