commit b95189b7e34a458f09454cff8001ed06df377704
parent 84c77855467e5cb7ad6ec5af5ce76fbacbae04f4
Author: zeertzjq <zeertzjq@outlook.com>
Date: Sun, 1 Jun 2025 23:11:52 +0800
Merge pull request #34244 from brianhuster/vim-6fea0a5
vim-patch: document on how to write lang annotation for codeblock in help file
Diffstat:
2 files changed, 35 insertions(+), 8 deletions(-)
diff --git a/runtime/doc/helphelp.txt b/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
diff --git 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 <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
