From: Shougo Matsushita Date: Wed, 25 Dec 2024 09:55:48 +0000 (+0100) Subject: runtime(help): Add better support for language annotation highlighting X-Git-Tag: v9.1.0962~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5ddcecf05febcdd374f47bea856830c3b6d1bff8;p=thirdparty%2Fvim.git runtime(help): Add better support for language annotation highlighting closes: #16238 Co-authored-by: Christian Brabandt Co-authored-by: h_east Signed-off-by: Shougo Matsushita Signed-off-by: Christian Brabandt --- diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index 948ef72488..5ab112d60d 100644 --- a/runtime/doc/helphelp.txt +++ b/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 , or as a Ctrl character as in CTRL-X diff --git a/runtime/doc/os_dos.txt b/runtime/doc/os_dos.txt index 96ef39d6fd..03c88dc474 100644 --- a/runtime/doc/os_dos.txt +++ b/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: > -c "command name" >file -For Win32 as: +For Win32 as: > -c "command name >file" For DOS 32 bit, DJGPP does this internally somehow. diff --git a/runtime/doc/tags b/runtime/doc/tags index 0f5bb0ee91..2e97186d2b 100644 --- a/runtime/doc/tags +++ b/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* diff --git a/runtime/syntax/help.vim b/runtime/syntax/help.vim index 3886164b33..ec5739faa4 100644 --- a/runtime/syntax/help.vim +++ b/runtime/syntax/help.vim @@ -1,7 +1,7 @@ " Vim syntax file " Language: Vim help file " Maintainer: The Vim Project -" Last Change: 2024 Dec 15 +" Last Change: 2024 Dec 25 " Former Maintainer: Bram Moolenaar " 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=/^[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=/^[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=/^