feat(help): highlighted codeblocks

6 files changed, 70 insertions, 61 deletions

diff --git a/cmake.deps/CMakeLists.txt b/cmake.deps/CMakeLists.txt
index 9c92d1a71c..28d60c45eb 100644
--- a/cmake.deps/CMakeLists.txt
+++ b/cmake.deps/CMakeLists.txt
@@ -203,8 +203,8 @@ set(TREESITTER_LUA_SHA256 930d0370dc15b66389869355c8e14305b9ba7aafd36edbfdb468c8
 set(TREESITTER_VIM_URL https://github.com/vigoux/tree-sitter-viml/archive/55ff1b080c09edeced9b748cf4c16d0b49d17fb9.tar.gz)
 set(TREESITTER_VIM_SHA256 1b1cd39e33c8fb02fa7fe3977e844883c2a8508a7edd621f2d21e39a9aeefa92)
 
-set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/v1.2.5.tar.gz)
-set(TREESITTER_HELP_SHA256 379d764937a0e3a38e3f9ce9a62c93ba24211a236c74181dd04ee3b4631472a8)
+set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/ce20f13c3f12506185754888feaae3f2ad54c287.tar.gz)
+set(TREESITTER_HELP_SHA256 2b8b166438cce66064aab56a744430b1f44871f43e47f70b51246d14bb826609)
 
 set(TREESITTER_URL https://github.com/tree-sitter/tree-sitter/archive/v0.20.7.tar.gz)
 set(TREESITTER_SHA256 b355e968ec2d0241bbd96748e00a9038f83968f85d822ecb9940cbe4c42e182e)
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index bcbbd69f11..93471b50ad 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -12,7 +12,7 @@ Lua engine                                                           *lua* *Lua*
 INTRODUCTION                                                       *lua-intro*
 
 The Lua 5.1 script engine is builtin and always available. Try this command to
-get an idea of what lurks beneath: >
+get an idea of what lurks beneath: >vim
 
     :lua print(vim.inspect(package.loaded))
 
@@ -56,20 +56,20 @@ https://www.lua.org/doc/cacm2018.pdf
   versatile control for both Lua and its host (Nvim).
 
                                                            *lua-call-function*
-Lua functions can be called in multiple ways. Consider the function: >
+Lua functions can be called in multiple ways. Consider the function: >lua
     local foo = function(a, b)
         print("A: ", a)
         print("B: ", b)
     end
 
-The first way to call this function is: >
+The first way to call this function is: >lua
     foo(1, 2)
     -- ==== Result ====
     -- A: 1
     -- B: 2
 
 This way of calling a function is familiar from most scripting languages.
-In Lua, any missing arguments are passed as `nil`. Example: >
+In Lua, any missing arguments are passed as `nil`. Example: >lua
     foo(1)
     -- ==== Result ====
     -- A: 1
@@ -81,7 +81,7 @@ discarded.
 It is also allowed to omit the parentheses (only) if the function takes
 exactly one string (`"foo"`) or table literal (`{1,2,3}`). The latter is often
 used to approximate the "named parameters" feature of languages like Python
-("kwargs" or "keyword args"). Example: >
+("kwargs" or "keyword args"). Example: >lua
     local func_with_opts = function(opts)
         local will_do_foo = opts.foo
         local filename = opts.filename
@@ -95,7 +95,7 @@ There is nothing special going on here except that parentheses are treated as
 whitespace. But visually, this small bit of sugar gets reasonably close to
 a "keyword args" interface.
 
-It is of course also valid to call the function with parentheses: >
+It is of course also valid to call the function with parentheses: >lua
 
     func_with_opts({ foo = true, filename = "hello.world" })
 <
@@ -108,7 +108,7 @@ Lua intentionally does not support regular expressions, instead it has limited
 "patterns" which avoid the performance pitfalls of extended regex.
 |luaref-patterns|
 
-Examples using |string.match()|: >
+Examples using |string.match()|: >lua
 
     print(string.match("foo123bar123", "%d+"))
     -- 123
@@ -205,7 +205,7 @@ Note:
 
 - Although adjustments happen automatically, Nvim does not track current
   values of |package.path| or |package.cpath|. If you happen to delete some
-  paths from there you can set 'runtimepath' to trigger an update: >
+  paths from there you can set 'runtimepath' to trigger an update: >vim
       let &runtimepath = &runtimepath
 
 - Skipping paths from 'runtimepath' which contain semicolons applies both to
@@ -231,11 +231,11 @@ arguments separated by " " (space) instead of "\t" (tab).
     chunk is evaluated as an expression and printed. `:lua =expr` is
     equivalent to `:lua print(vim.inspect(expr))`
 
-    Examples: >
+    Examples: >vim
         :lua vim.api.nvim_command('echo "Hello, Nvim!"')
-<    To see the Lua version: >
+<    To see the Lua version: >vim
         :lua print(_VERSION)
-<    To see the LuaJIT version: >
+<    To see the LuaJIT version: >vim
         :lua =jit.version
 <
                                                                 *:lua-heredoc*
@@ -246,7 +246,7 @@ arguments separated by " " (space) instead of "\t" (tab).
     be preceded by whitespace. You can omit [endmarker] after the "<<" and use
     a dot "." after {script} (similar to |:append|, |:insert|).
 
-    Example: >
+    Example: >vim
         function! CurrentLineInfo()
         lua << EOF
         local linenr = vim.api.nvim_win_get_cursor(0)[1]
@@ -268,7 +268,7 @@ arguments separated by " " (space) instead of "\t" (tab).
     that becomes the text of the corresponding buffer line. Default [range] is
     the whole file: "1,$".
 
-    Examples: >
+    Examples: >vim
         :luado return string.format("%s\t%d", line:reverse(), #line)
 
         :lua require"lpeg"
@@ -282,7 +282,7 @@ arguments separated by " " (space) instead of "\t" (tab).
     The whole argument is used as the filename (like |:edit|), spaces do not
     need to be escaped. Alternatively you can |:source| Lua files.
 
-    Examples: >
+    Examples: >vim
         :luafile script.lua
         :luafile %
 <
@@ -293,7 +293,7 @@ luaeval()                                                 *lua-eval* *luaeval()*
 The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is
 "luaeval". "luaeval" takes an expression string and an optional argument used
 for _A inside expression and returns the result of the expression. It is
-semantically equivalent in Lua to: >
+semantically equivalent in Lua to: >lua
 
     local chunkheader = "local _A = select(1, ...) return "
     function luaeval (expstr, arg)
@@ -307,11 +307,11 @@ converted to a |Blob|. Conversion of other Lua types is an error.
 
 The magic global "_A" contains the second argument to luaeval().
 
-Example: >
+Example: >vim
     :echo luaeval('_A[1] + _A[2]', [40, 2])
-    42
+    " 42
     :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123')
-    foo
+    " foo
 <
 Lua tables are used as both dictionaries and lists, so it is impossible to
 determine whether empty table is meant to be empty list or empty dictionary.
@@ -343,7 +343,7 @@ cases there is the following agreement:
      form a 1-step sequence from 1 to N are ignored, as well as all
      non-integral keys.
 
-Examples: >
+Examples: >vim
 
     :echo luaeval('math.pi')
     :function Rand(x,y) " random uniform between x and y
@@ -360,16 +360,16 @@ treated specially.
 Vimscript v:lua interface                                         *v:lua-call*
 
 From Vimscript the special `v:lua` prefix can be used to call Lua functions
-which are global or accessible from global tables. The expression >
+which are global or accessible from global tables. The expression >vim
     v:lua.func(arg1, arg2)
-is equivalent to the Lua chunk >
+is equivalent to the Lua chunk >lua
     return func(...)
-where the args are converted to Lua values. The expression >
+where the args are converted to Lua values. The expression >vim
     v:lua.somemod.func(args)
-is equivalent to the Lua chunk >
+is equivalent to the Lua chunk >lua
     return somemod.func(...)
 
-In addition, functions of packages can be accessed like >
+In addition, functions of packages can be accessed like >vim
     v:lua.require'mypack'.func(arg1, arg2)
     v:lua.require'mypack.submod'.func(arg1, arg2)
 Note: Only single quote form without parens is allowed. Using
@@ -378,11 +378,11 @@ is still valid as a function call of itself, in case require returns a useful
 value).
 
 The `v:lua` prefix may be used to call Lua functions as |method|s. For
-example: >
+example: >vim
     arg1->v:lua.somemod.func(arg2)
 <
 You can use `v:lua` in "func" options like 'tagfunc', 'omnifunc', etc.
-For example consider the following Lua omnifunc handler: >
+For example consider the following Lua omnifunc handler: >lua
 
     function mymod.omnifunc(findstart, base)
       if findstart == 1 then
@@ -397,7 +397,7 @@ Note: The module ("mymod" in the above example) must either be a Lua global,
 or use the require syntax as specified above to access it from a package.
 
 Note: `v:lua` without a call is not allowed in a Vimscript expression:
-|Funcref|s cannot represent Lua functions. The following are errors: >
+|Funcref|s cannot represent Lua functions. The following are errors: >vim
 
     let g:Myvar = v:lua.myfunc        " Error
     call SomeFunc(v:lua.mycallback)   " Error
@@ -411,7 +411,7 @@ The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
 various functions and sub-modules. It is always loaded, thus `require("vim")`
 is unnecessary.
 
-You can peek at the module properties: >
+You can peek at the module properties: >vim
 
     :lua print(vim.inspect(vim))
 
@@ -431,7 +431,7 @@ Result is something like this: >
       ...
     }
 
-To find documentation on e.g. the "deepcopy" function: >
+To find documentation on e.g. the "deepcopy" function: >vim
 
     :help vim.deepcopy()
 
@@ -443,7 +443,7 @@ VIM.LOOP                                                   *lua-loop* *vim.loop*
 
 `vim.loop` exposes all features of the Nvim event-loop. This is a low-level
 API that provides functionality for networking, filesystem, and process
-management. Try this command to see available functions: >
+management. Try this command to see available functions: >vim
 
     :lua print(vim.inspect(vim.loop))
 <
@@ -452,14 +452,14 @@ see |luv-intro| for a full reference manual.
 
                                                     *E5560* *lua-loop-callbacks*
 It is an error to directly invoke `vim.api` functions (except |api-fast|) in
-`vim.loop` callbacks. For example, this is an error: >
+`vim.loop` callbacks. For example, this is an error: >lua
 
     local timer = vim.loop.new_timer()
     timer:start(1000, 0, function()
       vim.api.nvim_command('echomsg "test"')
     end)
 <
-To avoid the error use |vim.schedule_wrap()| to defer the callback: >
+To avoid the error use |vim.schedule_wrap()| to defer the callback: >lua
 
     local timer = vim.loop.new_timer()
     timer:start(1000, 0, vim.schedule_wrap(function()
@@ -471,7 +471,7 @@ wrapping.)
 
 Example: repeating timer
     1. Save this code to a file.
-    2. Execute it with ":luafile %". >
+    2. Execute it with ":luafile %". >lua
 
     -- Create a timer handle (implementation detail: uv_timer_t).
     local timer = vim.loop.new_timer()
@@ -492,7 +492,7 @@ Example: File-change detection                                    *watch-file*
     3. Use ":Watch %" to watch any file.
     4. Try editing the file from another text editor.
     5. Observe that the file reloads in Nvim (because on_change() calls
-       |:checktime|). >
+       |:checktime|). >lua
 
     local w = vim.loop.new_fs_event()
     local function on_change(err, fname, status)
@@ -515,7 +515,7 @@ Example: TCP echo-server                                          *tcp-server*
     1. Save this code to a file.
     2. Execute it with ":luafile %".
     3. Note the port number.
-    4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >
+    4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >lua
 
     local function create_server(host, port, on_connect)
       local server = vim.loop.new_tcp()
@@ -564,16 +564,16 @@ VIM.HIGHLIGHT                                                  *lua-highlight*
 
 Nvim includes a function for highlighting a selection on yank (see for example
 https://github.com/machakann/vim-highlightedyank). To enable it, add
->
+>vim
     au TextYankPost * silent! lua vim.highlight.on_yank()
 <
 to your `init.vim`. You can customize the highlight group and the duration of
 the highlight via
->
+>vim
     au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
 <
 If you want to exclude visual selections from highlighting on yank, use
->
+>vim
     au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
 <
 vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
@@ -756,7 +756,7 @@ VIM                                                              *lua-builtin*
 
 vim.api.{func}({...})                                                *vim.api*
     Invokes Nvim |API| function {func} with arguments {...}.
-    Example: call the "nvim_get_current_line()" API function: >
+    Example: call the "nvim_get_current_line()" API function: >lua
         print(tostring(vim.api.nvim_get_current_line()))
 
 vim.version()                                                    *vim.version*
@@ -881,7 +881,7 @@ vim.wait({time} [, {callback}, {interval}, {fast_only}])          *vim.wait()*
 
         If {callback} errors, the error is raised.
 
-        Examples: >
+        Examples: >lua
 
     ---
     -- Wait for 100 ms, allowing other events to process
@@ -922,7 +922,7 @@ vim.ui_attach({ns}, {options}, {callback})                *vim.ui_attach()*
     used to handle messages when setting 'cmdheight' to zero (which is
     likewise experimental).
 
-    Example (stub for a |ui-popupmenu| implementation): >
+    Example (stub for a |ui-popupmenu| implementation): >lua
 
       ns = vim.api.nvim_create_namespace('my_fancy_pum')
 
@@ -950,7 +950,7 @@ vim.type_idx                                                    *vim.type_idx*
 
 vim.val_idx                                                      *vim.val_idx*
     Value index for tables representing |Float|s. A table representing
-    floating-point value 1.0 looks like this: >
+    floating-point value 1.0 looks like this: >lua
         {
           [vim.type_idx] = vim.types.float,
           [vim.val_idx] = 1.0,
@@ -997,7 +997,7 @@ See also https://github.com/nanotee/nvim-lua-guide.
 vim.call({func}, {...})                                           *vim.call()*
     Invokes |vim-function| or |user-function| {func} with arguments {...}.
     See also |vim.fn|.
-    Equivalent to: >
+    Equivalent to: >lua
         vim.fn[func]({...})
 
 vim.cmd({command})
@@ -1005,7 +1005,7 @@ vim.cmd({command})
 
 vim.fn.{func}({...})                                                  *vim.fn*
     Invokes |vim-function| or |user-function| {func} with arguments {...}.
-    To call autoload functions, use the syntax: >
+    To call autoload functions, use the syntax: >lua
         vim.fn['some#function']({...})
 <
     Unlike vim.api.|nvim_call_function()| this converts directly between Vim
@@ -1028,7 +1028,7 @@ from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
 described below. In this way you can easily read and modify global Vimscript
 variables from Lua.
 
-Example: >
+Example: >lua
 
     vim.g.foo = 5     -- Set the g:foo Vimscript variable.
     print(vim.g.foo)  -- Get and print the g:foo Vimscript variable.
@@ -1041,7 +1041,7 @@ Nvim. This is because the index into the namespace simply returns a copy.
 Instead the whole dictionary must be written as one. This can be achieved by
 creating a short-lived temporary.
 
-Example: >
+Example: >lua
 
     vim.g.my_dict.field1 = 'value'  -- Does not work
 
@@ -1076,7 +1076,7 @@ vim.env                                                              *vim.env*
     Environment variables defined in the editor session.
     See |expand-env| and |:let-environment| for the Vimscript behavior.
     Invalid or unset key returns `nil`.
-    Example: >
+    Example: >lua
         vim.env.FOO = 'bar'
         print(vim.env.TERM)
 <
@@ -1110,7 +1110,7 @@ vim.o                                                                  *vim.o*
     Note: this works on both buffer-scoped and window-scoped options using the
     current buffer and window.
 
-    Example: >
+    Example: >lua
         vim.o.cmdheight = 4
         print(vim.o.columns)
         print(vim.o.foo)     -- error: invalid key
@@ -1123,7 +1123,7 @@ vim.go                                                                *vim.go*
     option value and thus is mostly useful for use with |global-local|
     options.
 
-    Example: >
+    Example: >lua
         vim.go.cmdheight = 4
         print(vim.go.columns)
         print(vim.go.bar)     -- error: invalid key
@@ -1135,7 +1135,7 @@ vim.bo[{bufnr}]                                                                *
 
     Note: this is equivalent to both `:set` and `:setlocal`.
 
-    Example: >
+    Example: >lua
         local bufnr = vim.api.nvim_get_current_buf()
         vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
         print(vim.bo.comments)
@@ -1146,11 +1146,11 @@ vim.wo[{winid}]                                                                *
     Like `:set`. If [{winid}] is omitted then the current window is used.
     Invalid {winid} or key is an error.
 
-    Note: this does not access |local-options| (`:setlocal`) instead use: >
+    Note: this does not access |local-options| (`:setlocal`) instead use: >lua
         nvim_get_option_value(OPTION, { scope = 'local', win = winid })
         nvim_set_option_value(OPTION, VALUE, { scope = 'local', win = winid }
 <
-    Example: >
+    Example: >lua
         local winid = vim.api.nvim_get_current_win()
         vim.wo[winid].number = true    -- same as vim.wo.number = true
         print(vim.wo.foldmarker)
@@ -1232,7 +1232,7 @@ Option:get()
     values will be returned in exactly the same fashion.
 
     For values that are comma-separated lists, an array will be returned with
-    the values as entries in the array: >
+    the values as entries in the array: >lua
         vim.cmd [[set wildignore=*.pyc,*.o]]
 
         vim.pretty_print(vim.opt.wildignore:get())
@@ -1245,7 +1245,7 @@ Option:get()
         -- Will ignore: *.o
 <
     For values that are comma-separated maps, a table will be returned with
-    the names as keys and the values as entries: >
+    the names as keys and the values as entries: >lua
         vim.cmd [[set listchars=space:_,tab:>~]]
 
         vim.pretty_print(vim.opt.listchars:get())
@@ -1256,7 +1256,7 @@ Option:get()
         end
 <
     For values that are lists of flags, a set will be returned with the flags
-    as keys and `true` as entries. >
+    as keys and `true` as entries. >lua
         vim.cmd [[set formatoptions=njtcroql]]
 
         vim.pretty_print(vim.opt.formatoptions:get())
diff --git a/runtime/queries/help/highlights.scm b/runtime/queries/help/highlights.scm
index b2ed390336..c0d88301bc 100644
--- a/runtime/queries/help/highlights.scm
+++ b/runtime/queries/help/highlights.scm
@@ -17,7 +17,7 @@
    text: (_) @text.literal)
 (codeblock) @text.literal
 (codeblock
-   ">" @conceal (#set! conceal ""))
+   [">" (language)] @conceal (#set! conceal ""))
 (block
    "<" @conceal (#set! conceal ""))
 (argument) @parameter
diff --git a/runtime/queries/help/injections.scm b/runtime/queries/help/injections.scm
new file mode 100644
index 0000000000..09bbe44e84
--- /dev/null
+++ b/runtime/queries/help/injections.scm
@@ -0,0 +1,3 @@
+(codeblock
+  (language) @language
+  (code) @content)
diff --git a/runtime/syntax/help.vim b/runtime/syntax/help.vim
index 181fed8708..c026c41799 100644
--- a/runtime/syntax/help.vim
+++ b/runtime/syntax/help.vim
@@ -14,10 +14,11 @@ set cpo&vim
 syn match helpHeadline		"^[A-Z.][-A-Z0-9 .,()_']*?\=\ze\(\s\+\*\|$\)"
 syn match helpSectionDelim	"^===.*===$"
 syn match helpSectionDelim	"^---.*--$"
+" Neovim: support language annotation in codeblocks
 if has("conceal")
-  syn region helpExample	matchgroup=helpIgnore start=" >$" start="^>$" end="^[^ \t]"me=e-1 end="^<" concealends
+  syn region helpExample	matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^[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 helpExample	matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^[a-z0-9]*>$" end="^[^ \t]"me=e-1 end="^<"
 endif
 syn match helpHyperTextJump	"\\\@<!|[#-)!+-~]\+|" contains=helpBar
 syn match helpHyperTextEntry	"\*[#-)!+-~]\+\*\s"he=e-1 contains=helpStar
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index e5251b7f25..e5e99b308a 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -489,7 +489,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
     end
     return string.format('<div class="help-para">\n%s\n</div>\n', text)
   elseif node_name == 'line' then
-    if parent ~= 'codeblock' and (is_blank(text) or is_noise(text, stats.noise_lines)) then
+    if parent ~= 'code' and (is_blank(text) or is_noise(text, stats.noise_lines)) then
       return ''  -- Discard common "noise" lines.
     end
     -- XXX: Avoid newlines (too much whitespace) after block elements in old (preformatted) layout.
@@ -535,7 +535,12 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
     return s
   elseif node_name == 'argument' then
     return ('%s<code>{%s}</code>'):format(ws(), text)
+  -- TODO: use language for proper syntax highlighted code blocks
   elseif node_name == 'codeblock' then
+    return text
+  elseif node_name == 'language' then
+    return ''
+  elseif node_name == 'code' then
     if is_blank(text) then
       return ''
     end