runtime(help): Add better support for language annotation highlighting
Commit:
https://github.com/vim/vim/commit/5ddcecf05febcdd374f47bea856830c3b6d1bff8
Author: Shougo Matsushita <shougo.ma...@gmail.com>
Date: Wed Dec 25 10:55:48 2024 +0100
runtime(help): Add better support for language annotation highlighting
closes: https://github.com/vim/vim/issues/16238
Co-authored-by: Christian Brabandt <c...@256bit.org>
Co-authored-by: h_east <h.east....@gmail.com>
Signed-off-by: Shougo Matsushita <shougo.ma...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
index 948ef7248..5ab112d60 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 <PageDown>, or
as a Ctrl character as in CTRL-X
diff --git a/runtime/doc/os_dos.txt b/runtime/doc/os_dos.txt
index 96ef39d6f..03c88dc47 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: >
<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.
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 0f5bb0ee9..2e97186d2 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 3886164b3..ec5739faa 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 <https://github.com/vim/vim>
-" Last Change: 2024 Dec 15
+" Last Change: 2024 Dec 25
" Former Maintainer: Bram Moolenaar <b...@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="^[^ ]"me=e-1 end="^<" concealends
- syn region helpExampleVimScript matchgroup=helpIgnore
- \ start=/^>vim$/ start=/ >vim$/
- \ end=/^[^ ]/me=e-1 end=/^</ concealends
- \ contains=@VimScript keepend
+ syn region helpExample matchgroup=helpIgnore
+ \ start="\%(^\| \)>[a-z0-9]*$" end="^[^ ]"me=e-1 end="^<"
concealends
else
- syn region helpExample matchgroup=helpIgnore start=" >$" start="^>$"
end="^[^ ]"me=e-1 end="^<"
- syn region helpExampleVimScript matchgroup=helpIgnore
- \ start=/^>vim$/ start=/ >vim$/
- \ end=/^[^ ]/me=e-1 end=/^</
- \ contains=@VimScript keepend
+ syn region helpExample matchgroup=helpIgnore
+ \ start="\%(^\| \)>[a-z0-9]*$" end="^[^ ]"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=/^[^ ]/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
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1tQOBP-002aRs-6U%40256bit.org.
