fix(treesitter): document more standard highlight groups

Problem: Not all standard treesitter groups are documented.

Solution: Document them all (without relying on fallback); add default
link for new `*.builtin` groups to `Special` and `@keyword.type` to
`Structure`. Remove `@markup.environment.*` which only made sense for
LaTeX.

runtime/colors/vim.lua

@@ -158,18 +158,22 @@ hi('@boolean',           { link = 'Boolean' })
 hi('@number.float',      { link = 'Float' })
 
 -- Functions
-hi('@function',           { link = 'Function' })
+hi('@function',                   { link = 'Function' })
-hi('@function.builtin',   { link = 'Special' })
+hi('@function.builtin',           { link = 'Special' })
-hi('@function.macro',     { link = 'Macro' })
+hi('@function.macro',             { link = 'Macro' })
-hi('@variable.parameter', { link = 'Identifier' })
+hi('@function.method',            { link = 'Function' })
-hi('@function.method',    { link = 'Function' })
+hi('@variable.parameter',         { link = 'Identifier' })
-hi('@variable.member',    { link = 'Identifier' })
+hi('@variable.parameter.builtin', { link = 'Special' })
-hi('@property',           { link = 'Identifier' })
+hi('@variable.member',            { link = 'Identifier' })
-hi('@constructor',        { link = 'Special' })
+hi('@property',                   { link = 'Identifier' })
+hi('@attribute',                  { link = 'Macro' })
+hi('@attribute.builtin',          { link = 'Special' })
+hi('@constructor',                { link = 'Special' })
 
 -- Keywords
 hi('@keyword.conditional', { link = 'Conditional' })
 hi('@keyword.repeat',      { link = 'Repeat' })
+hi('@keyword.type',        { link = 'Structure' })
 hi('@label',               { link = 'Label' })
 hi('@operator',            { link = 'Operator' })
 hi('@keyword',             { link = 'Keyword' })
@@ -178,12 +182,12 @@ hi('@keyword.exception',   { link = 'Exception' })
 hi('@variable',          { link = 'Identifier' })
 hi('@type',              { link = 'Type' })
 hi('@type.definition',   { link = 'Typedef' })
-hi('@keyword.storage',   { link = 'StorageClass' })
 hi('@module',            { link = 'Identifier' })
 hi('@keyword.import',    { link = 'Include' })
 hi('@keyword.directive', { link = 'PreProc' })
 hi('@keyword.debug',     { link = 'Debug' })
 hi('@tag',               { link = 'Tag' })
+hi('@tag.builtin',       { link = 'Special' })
 
 -- LSP semantic tokens
 hi('@lsp.type.class',         { link = 'Structure' })

runtime/doc/treesitter.txt

@@ -469,10 +469,11 @@ The following is a list of standard captures used in queries for Nvim,
 highlighted according to the current colorscheme (use |:Inspect| on one to see
 the exact definition):
 
-@variable               various variable names
+@variable                       various variable names
-@variable.builtin       built-in variable names (e.g. `this` / `self`)
+@variable.builtin               built-in variable names (e.g. `this`, `self`)
-@variable.parameter     parameters of a function
+@variable.parameter             parameters of a function
-@variable.member        object and struct fields
+@variable.parameter.builtin     special parameters (e.g. `_`, `it`)
+@variable.member                object and struct fields
 
 @constant               constant identifiers
 @constant.builtin       built-in constant values
@@ -480,7 +481,7 @@ the exact definition):
 
 @module                 modules or namespaces
 @module.builtin         built-in modules or namespaces
-@label                  GOTO and other labels (e.g. `label:` in C), including heredoc labels
+@label                  `GOTO` and other labels (e.g. `label:` in C), including heredoc labels
 
 @string                 string literals
 @string.documentation   string documenting code (e.g. Python docstrings)
@@ -501,9 +502,9 @@ the exact definition):
 @type                   type or class definitions and annotations
 @type.builtin           built-in types
 @type.definition        identifiers in type definitions (e.g. `typedef <type> <identifier>` in C)
-@type.qualifier         type qualifiers (e.g. `const`)
 
-@attribute              attribute annotations (e.g. Python decorators)
+@attribute              attribute annotations (e.g. Python decorators, Rust lifetimes)
+@attribute.builtin      builtin annotations (e.g. `@property` in Python)
 @property               the key in key/value pairs
 
 @function               function definitions
@@ -515,27 +516,28 @@ the exact definition):
 @function.method.call   method calls
 
 @constructor            constructor calls and definitions
-@operator               symbolic operators (e.g. `+` / `*`)
+@operator               symbolic operators (e.g. `+`, `*`)
 
 @keyword                keywords not fitting into specific categories
 @keyword.coroutine      keywords related to coroutines (e.g. `go` in Go, `async/await` in Python)
 @keyword.function       keywords that define a function (e.g. `func` in Go, `def` in Python)
-@keyword.operator       operators that are English words (e.g. `and` / `or`)
+@keyword.operator       operators that are English words (e.g. `and`, `or`)
-@keyword.import         keywords for including modules (e.g. `import` / `from` in Python)
+@keyword.import         keywords for including modules (e.g. `import`, `from` in Python)
-@keyword.storage        modifiers that affect storage in memory or life-time
+@keyword.type           keywords defining composite types (e.g. `struct`, `enum`)
-@keyword.repeat         keywords related to loops (e.g. `for` / `while`)
+@keyword.modifier       keywords definining type modifiers (e.g. `const`, `static`, `public`)
+@keyword.repeat         keywords related to loops (e.g. `for`, `while`)
 @keyword.return         keywords like `return` and `yield`
 @keyword.debug          keywords related to debugging
-@keyword.exception      keywords related to exceptions (e.g. `throw` / `catch`)
+@keyword.exception      keywords related to exceptions (e.g. `throw`, `catch`)
 
-@keyword.conditional         keywords related to conditionals (e.g. `if` / `else`)
+@keyword.conditional         keywords related to conditionals (e.g. `if`, `else`)
-@keyword.conditional.ternary ternary operator (e.g. `?` / `:`)
+@keyword.conditional.ternary ternary operator (e.g. `?`, `:`)
 
 @keyword.directive           various preprocessor directives and shebangs
 @keyword.directive.define    preprocessor definition directives
 
-@punctuation.delimiter  delimiters (e.g. `;` / `.` / `,`)
+@punctuation.delimiter  delimiters (e.g. `;`, `.`, `,`)
-@punctuation.bracket    brackets (e.g. `()` / `{}` / `[]`)
+@punctuation.bracket    brackets (e.g. `()`, `{}`, `[]`)
 @punctuation.special    special symbols (e.g. `{}` in string interpolation)
 
 @comment                line and block comments
@@ -543,7 +545,7 @@ the exact definition):
 
 @comment.error          error-type comments (e.g. `ERROR`, `FIXME`, `DEPRECATED`)
 @comment.warning        warning-type comments (e.g. `WARNING`, `FIX`, `HACK`)
-@comment.todo           todo-type comments (e.g. `TODO`, `WIP`, `FIXME`)
+@comment.todo           todo-type comments (e.g. `TODO`, `WIP`)
 @comment.note           note-type comments (e.g. `NOTE`, `INFO`, `XXX`)
 
 @markup.strong          bold text
@@ -552,10 +554,15 @@ the exact definition):
 @markup.underline       underlined text (only for literal underline markup!)
 
 @markup.heading         headings, titles (including markers)
+@markup.heading.1       top-level heading
+@markup.heading.2       section heading
+@markup.heading.3       subsection heading
+@markup.heading.4       and so on
+@markup.heading.5       and so forth
+@markup.heading.6       six levels ought to be enough for anybody
 
 @markup.quote           block quotes
 @markup.math            math environments (e.g. `$ ... $` in LaTeX)
-@markup.environment     environments (e.g. in LaTeX)
 
 @markup.link            text references, footnotes, citations, etc.
 @markup.link.label      link, reference descriptions
@@ -573,6 +580,7 @@ the exact definition):
 @diff.delta             changed text (for diff files)
 
 @tag                    XML-style tag names (e.g. in XML, HTML, etc.)
+@tag.builtin            XML-style tag names (e.g. HTML5 tags)
 @tag.attribute          XML-style tag attributes
 @tag.delimiter          XML-style tag delimiters
 

src/nvim/highlight_group.c

@@ -223,7 +223,8 @@ static const char *highlight_init_both[] = {
   "default link DiagnosticUnnecessary      Comment",
 
   // Treesitter standard groups
-  "default link @variable.builtin Special",
+  "default link @variable.builtin           Special",
+  "default link @variable.parameter.builtin Special",
 
   "default link @constant         Constant",
   "default link @constant.builtin Special",
@@ -248,8 +249,9 @@ static const char *highlight_init_both[] = {
   "default link @type         Type",
   "default link @type.builtin Special",
 
-  "default link @attribute Macro",
+  "default link @attribute         Macro",
-  "default link @property  Identifier",
+  "default link @attribute.builtin Special",
+  "default link @property          Identifier",
 
   "default link @function         Function",
   "default link @function.builtin Special",
@@ -282,7 +284,8 @@ static const char *highlight_init_both[] = {
   "default link @diff.minus Removed",
   "default link @diff.delta Changed",
 
-  "default link @tag Tag",
+  "default link @tag         Tag",
+  "default link @tag.builtin Special",
 
   // LSP semantic tokens
   "default link @lsp.type.class         @type",

test/old/testdir/test_syntax.vim

@@ -197,14 +197,14 @@ func Test_syntax_completion()
   " Check that clearing "Aap" avoids it showing up before Boolean.
   hi @Aap ctermfg=blue
   call feedkeys(":syn list \<C-A>\<C-B>\"\<CR>", 'tx')
-  call assert_match('^"syn list @Aap @attribute @boolean @character ', @:)
+  call assert_match('^"syn list @Aap @attribute @attribute.builtin @boolean @character ', @:)
   hi clear @Aap
 
   call feedkeys(":syn list \<C-A>\<C-B>\"\<CR>", 'tx')
-  call assert_match('^"syn list @attribute @boolean @character ', @:)
+  call assert_match('^"syn list @attribute @attribute.builtin @boolean @character ', @:)
 
   call feedkeys(":syn match \<C-A>\<C-B>\"\<CR>", 'tx')
-  call assert_match('^"syn match @attribute @boolean @character ', @:)
+  call assert_match('^"syn match @attribute @attribute.builtin @boolean @character ', @:)
 
   syn cluster Aax contains=Aap
   call feedkeys(":syn list @A\<C-A>\<C-B>\"\<CR>", 'tx')