diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index bb7358a380..44655e50e6 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -373,17 +373,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 , or as a Ctrl character as in CTRL-X diff --git a/runtime/syntax/help.vim b/runtime/syntax/help.vim index 3806269e6b..89522f7ab3 100644 --- a/runtime/syntax/help.vim +++ b/runtime/syntax/help.vim @@ -12,28 +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 - -" 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 helpExampleVimScript matchgroup=helpIgnore - \ start=/^>vim$/ start=/ >vim$/ - \ end=/^[^ \t]/me=e-1 end=/^[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 helpExampleVimScript matchgroup=helpIgnore - \ start=/^>vim$/ start=/ >vim$/ - \ end=/^[^ \t]/me=e-1 end=/^[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=/^