From 11ae879ebd555b36dbc38d798dabf8641bb11f05 Mon Sep 17 00:00:00 2001 From: brianhuster Date: Sat, 31 May 2025 17:13:46 +0700 Subject: [PATCH 1/3] vim-patch:6fea0a5: runtime(help): Add Vim lang annotation support for codeblocks closes: vim/vim#16215 https://github.com/vim/vim/commit/6fea0a54804fc36ab7138a66210b0eb380d96198 Co-authored-by: Shougo Matsushita Co-authored-by: zeertzjq --- runtime/doc/helphelp.txt | 8 +++++++- runtime/syntax/help.vim | 15 ++++++++++++++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index ef5b16ff42..bb7358a380 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -377,7 +377,13 @@ also implicitly stops the block of ex-commands before it. E.g. > 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"). +E.g: >vim + function Example_Func() + echo "Example" + endfunction +< 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 c8ad8bfe4a..3806269e6b 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 Oct 16 +" Last Change: 2024 Dec 15 " Former Maintainer: Bram Moolenaar " Quit when a (custom) syntax file was already loaded @@ -15,11 +15,24 @@ set cpo&vim 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]*$" 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=/^ Date: Sat, 31 May 2025 19:54:52 +0700 Subject: [PATCH 2/3] vim-patch:5ddcecf: runtime(help): Add better support for language annotation highlighting closes: vim/vim#16238 https://github.com/vim/vim/commit/5ddcecf05febcdd374f47bea856830c3b6d1bff8 Co-authored-by: Shougo Matsushita Co-authored-by: Christian Brabandt Co-authored-by: h_east --- runtime/doc/helphelp.txt | 37 +++++++++++++++++++++++++++++-------- runtime/syntax/help.vim | 38 +++++++++++++++++++++++--------------- 2 files changed, 52 insertions(+), 23 deletions(-) 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=/^ Date: Sat, 31 May 2025 19:58:16 +0700 Subject: [PATCH 3/3] vim-patch:b9ea0a8: runtime(doc): tweak documentation style in helphelp.txt closes: vim/vim#16302 https://github.com/vim/vim/commit/b9ea0a89fadb53812860b8c2c1ca27e1d51a33da Co-authored-by: h-east I removed some parts that are not applicable to Nvim, like HelpTOC --- runtime/doc/helphelp.txt | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index 44655e50e6..a44d488729 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -377,33 +377,12 @@ also implicitly stops the block of ex-commands before it. E.g. > echo "Example" endfunction < - -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 +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 < - *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