docs: apply current colorscheme to default highlight groups

Problem: Not all default highlight groups show their actual colors.
Solution: Refactor `vimhelp.lua` and apply it to all relevant lists (UI
groups, syntax groups, treesitter groups, LSP groups, diagnostic groups).

5 files changed, 157 insertions, 134 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 40889f4255..65890953e0 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -480,23 +480,23 @@ Use |LspTokenUpdate| and |vim.lsp.semantic_tokens.highlight_token()| for more
 complex highlighting.
 
 The following groups are linked by default to standard |group-name|s:
->
-    @lsp.type.class         Structure
-    @lsp.type.decorator     Function
-    @lsp.type.enum          Structure
-    @lsp.type.enumMember    Constant
-    @lsp.type.function      Function
-    @lsp.type.interface     Structure
-    @lsp.type.macro         Macro
-    @lsp.type.method        Function
-    @lsp.type.namespace     Structure
-    @lsp.type.parameter     Identifier
-    @lsp.type.property      Identifier
-    @lsp.type.struct        Structure
-    @lsp.type.type          Type
-    @lsp.type.typeParameter TypeDef
-    @lsp.type.variable      Identifier
-<
+
+@lsp.type.class          Structure
+@lsp.type.decorator      Function
+@lsp.type.enum           Structure
+@lsp.type.enumMember     Constant
+@lsp.type.function       Function
+@lsp.type.interface      Structure
+@lsp.type.macro          Macro
+@lsp.type.method         Function
+@lsp.type.namespace      Structure
+@lsp.type.parameter      Identifier
+@lsp.type.property       Identifier
+@lsp.type.struct         Structure
+@lsp.type.type           Type
+@lsp.type.typeParameter  TypeDef
+@lsp.type.variable       Identifier
+
 ==============================================================================
 EVENTS                                                            *lsp-events*
 
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 1ca01a09e3..e859ddcadc 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -196,52 +196,52 @@ be preferred names for highlight groups that are common for many languages.
 These are the suggested group names (if syntax highlighting works properly
 you can see the actual color, except for "Ignore"):
 
-	 Comment	any comment
-
-	 Constant	any constant
-	 String		a string constant: "this is a string"
-	 Character	a character constant: 'c', '\n'
-	 Number		a number constant: 234, 0xff
-	 Boolean	a boolean constant: TRUE, false
-	 Float		a floating point constant: 2.3e10
-
-	 Identifier	any variable name
-	 Function	function name (also: methods for classes)
-
-	 Statement	any statement
-	 Conditional	if, then, else, endif, switch, etc.
-	 Repeat		for, do, while, etc.
-	 Label		case, default, etc.
-	 Operator	"sizeof", "+", "*", etc.
-	 Keyword	any other keyword
-	 Exception	try, catch, throw
-
-	 PreProc	generic Preprocessor
-	 Include	preprocessor #include
-	 Define		preprocessor #define
-	 Macro		same as Define
-	 PreCondit	preprocessor #if, #else, #endif, etc.
-
-	 Type		int, long, char, etc.
-	 StorageClass	static, register, volatile, etc.
-	 Structure	struct, union, enum, etc.
-	 Typedef	A typedef
-
-	 Special	any special symbol
-	 SpecialChar	special character in a constant
-	 Tag		you can use CTRL-] on this
-	 Delimiter	character that needs attention
-	 SpecialComment	special things inside a comment
-	 Debug		debugging statements
-
-	 Underlined	text that stands out, HTML links
-
-	 Ignore		left blank, hidden  |hl-Ignore|
-
-	 Error		any erroneous construct
-
-	 Todo		anything that needs extra attention; mostly the
-			keywords TODO FIXME and XXX
+Comment		any comment
+
+Constant	any constant
+String		a string constant: "this is a string"
+Character	a character constant: 'c', '\n'
+Number		a number constant: 234, 0xff
+Boolean		a boolean constant: TRUE, false
+Float		a floating point constant: 2.3e10
+
+Identifier	any variable name
+Function	function name (also: methods for classes)
+
+Statement	any statement
+Conditional	if, then, else, endif, switch, etc.
+Repeat		for, do, while, etc.
+Label		case, default, etc.
+Operator	"sizeof", "+", "*", etc.
+Keyword		any other keyword
+Exception	try, catch, throw
+
+PreProc		generic Preprocessor
+Include		preprocessor #include
+Define		preprocessor #define
+Macro		same as Define
+PreCondit	preprocessor #if, #else, #endif, etc.
+
+Type		int, long, char, etc.
+StorageClass	static, register, volatile, etc.
+Structure	struct, union, enum, etc.
+Typedef		a typedef
+
+Special		any special symbol
+SpecialChar	special character in a constant
+Tag		you can use CTRL-] on this
+Delimiter	character that needs attention
+SpecialComment	special things inside a comment
+Debug		debugging statements
+
+Underlined	text that stands out, HTML links
+
+Ignore		left blank, hidden  |hl-Ignore|
+
+Error		any erroneous construct
+
+Todo		anything that needs extra attention; mostly the
+		keywords TODO FIXME and XXX
 
 The names marked with * are the preferred groups; the others are minor groups.
 For the preferred groups, the "syntax.vim" file contains default highlighting.
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index e3836a357b..44d644f945 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -393,58 +393,58 @@ instance, to highlight comments differently per language: >vim
     hi link @comment.doc.java String
 <
 The following captures are linked by default to standard |group-name|s:
->
-    @text.literal      Comment
-    @text.reference    Identifier
-    @text.title        Title
-    @text.uri          Underlined
-    @text.underline    Underlined
-    @text.todo         Todo
-
-    @comment           Comment
-    @punctuation       Delimiter
-
-    @constant          Constant
-    @constant.builtin  Special
-    @constant.macro    Define
-    @define            Define
-    @macro             Macro
-    @string            String
-    @string.escape     SpecialChar
-    @string.special    SpecialChar
-    @character         Character
-    @character.special SpecialChar
-    @number            Number
-    @boolean           Boolean
-    @float             Float
-
-    @function          Function
-    @function.builtin  Special
-    @function.macro    Macro
-    @parameter         Identifier
-    @method            Function
-    @field             Identifier
-    @property          Identifier
-    @constructor       Special
-
-    @conditional       Conditional
-    @repeat            Repeat
-    @label             Label
-    @operator          Operator
-    @keyword           Keyword
-    @exception         Exception
-
-    @variable          Identifier
-    @type              Type
-    @type.definition   Typedef
-    @storageclass      StorageClass
-    @structure         Structure
-    @namespace         Identifier
-    @include           Include
-    @preproc           PreProc
-    @debug             Debug
-    @tag               Tag
-<
+
+@text.literal       Comment
+@text.reference     Identifier
+@text.title         Title
+@text.uri           Underlined
+@text.underline     Underlined
+@text.todo          Todo
+
+@comment            Comment
+@punctuation        Delimiter
+
+@constant           Constant
+@constant.builtin   Special
+@constant.macro     Define
+@define             Define
+@macro              Macro
+@string             String
+@string.escape      SpecialChar
+@string.special     SpecialChar
+@character          Character
+@character.special  SpecialChar
+@number             Number
+@boolean            Boolean
+@float              Float
+
+@function           Function
+@function.builtin   Special
+@function.macro     Macro
+@parameter          Identifier
+@method             Function
+@field              Identifier
+@property           Identifier
+@constructor        Special
+
+@conditional        Conditional
+@repeat             Repeat
+@label              Label
+@operator           Operator
+@keyword            Keyword
+@exception          Exception
+
+@variable           Identifier
+@type               Type
+@type.definition    Typedef
+@storageclass       StorageClass
+@structure          Structure
+@namespace          Identifier
+@include            Include
+@preproc            PreProc
+@debug              Debug
+@tag                Tag
+
                                                   *treesitter-highlight-spell*
 The special `@spell` capture can be used to indicate that a node should be
 spell checked by Nvim's builtin |spell| checker. For example, the following
diff --git a/runtime/ftplugin/help.lua b/runtime/ftplugin/help.lua
index bf3408c2d9..67c417b1be 100644
--- a/runtime/ftplugin/help.lua
+++ b/runtime/ftplugin/help.lua
@@ -2,6 +2,27 @@
 vim.treesitter.start()
 
 -- add custom highlights for list in `:h highlight-groups`
-if vim.endswith(vim.fs.normalize(vim.api.nvim_buf_get_name(0)), '/doc/syntax.txt') then
-  require('vim.vimhelp').highlight_groups()
+local bufname = vim.fs.normalize(vim.api.nvim_buf_get_name(0))
+if vim.endswith(bufname, '/doc/syntax.txt') then
+  require('vim.vimhelp').highlight_groups({
+    { start = [[\*group-name\*]], stop = '^======', match = '^(%w+)\t' },
+    { start = [[\*highlight-groups\*]], stop = '^======', match = '^(%w+)\t' },
+  })
+elseif vim.endswith(bufname, '/doc/treesitter.txt') then
+  require('vim.vimhelp').highlight_groups({
+    {
+      start = [[\*treesitter-highlight-groups\*]],
+      stop = [[\*treesitter-highlight-spell\*]],
+      match = '^@[%w%p]+',
+    },
+  })
+elseif vim.endswith(bufname, '/doc/diagnostic.txt') then
+  require('vim.vimhelp').highlight_groups({
+    { start = [[\*diagnostic-highlights\*]], stop = '^======', match = '^(%w+)' },
+  })
+elseif vim.endswith(bufname, '/doc/lsp.txt') then
+  require('vim.vimhelp').highlight_groups({
+    { start = [[\*lsp-highlight\*]], stop = '^------', match = '^(%w+)' },
+    { start = [[\*lsp-semantic-highlight\*]], stop = '^======', match = '^@[%w%p]+' },
+  })
 end
diff --git a/runtime/lua/vim/vimhelp.lua b/runtime/lua/vim/vimhelp.lua
index a4d6a50b12..4af6866d48 100644
--- a/runtime/lua/vim/vimhelp.lua
+++ b/runtime/lua/vim/vimhelp.lua
@@ -2,26 +2,28 @@
 
 local M = {}
 
--- Called when editing the doc/syntax.txt file
-function M.highlight_groups()
-  local save_cursor = vim.fn.getcurpos()
-
-  local start_lnum = vim.fn.search([[\*highlight-groups\*]], 'c')
-  if start_lnum == 0 then
-    return
-  end
-  local end_lnum = vim.fn.search('^======')
-  if end_lnum == 0 then
-    return
-  end
-
+--- Apply current colorscheme to lists of default highlight groups
+---
+--- Note: {patterns} is assumed to be sorted by occurrence in the file.
+--- @param patterns {start:string,stop:string,match:string}[]
+function M.highlight_groups(patterns)
   local ns = vim.api.nvim_create_namespace('vimhelp')
   vim.api.nvim_buf_clear_namespace(0, ns, 0, -1)
 
-  for lnum = start_lnum, end_lnum do
-    local word = vim.api.nvim_buf_get_lines(0, lnum - 1, lnum, true)[1]:match('^(%w+)\t')
-    if vim.fn.hlexists(word) ~= 0 then
-      vim.api.nvim_buf_set_extmark(0, ns, lnum - 1, 0, { end_col = #word, hl_group = word })
+  local save_cursor = vim.fn.getcurpos()
+
+  for _, pat in pairs(patterns) do
+    local start_lnum = vim.fn.search(pat.start, 'c')
+    local end_lnum = vim.fn.search(pat.stop)
+    if start_lnum == 0 or end_lnum == 0 then
+      break
+    end
+
+    for lnum = start_lnum, end_lnum do
+      local word = vim.api.nvim_buf_get_lines(0, lnum - 1, lnum, true)[1]:match(pat.match)
+      if vim.fn.hlexists(word) ~= 0 then
+        vim.api.nvim_buf_set_extmark(0, ns, lnum - 1, 0, { end_col = #word, hl_group = word })
+      end
     end
   end