feat!: align standard captures with upstream

Problem: Sharing highlight queries with upstream tree-sitter and
Helix is difficult.

Solution: Where reasonable, use capture names in tree-sitter's standard
list or Helix's Atom-style hierarchy.

Specifically:

* tree-sitter "standard capture names"
  (https://github.com/tree-sitter/tree-sitter/blob/3f44b896852eb7daaa6df4fb778c9bb52c70c815/highlight/src/lib.rs#L20-L72):

  - `@parameter` -> `@variable.parameter`
  - `@field` -> `@variable.member`
  - `@namespace` -> `@module`
  - `@float` -> `@number.float`
  - `@symbol` -> `@string.special.symbol`
  - `@string.regex` -> `@string.regexp`
  - `@text.*` -> `@markup.*` (`strong`, `italic`, `link`, `strikethrough`; with exceptions; see below)
  - `@text.title` -> `@markup.heading`
  - `@text.literal` -> `@markup.raw`
  - `@text.reference` -> `@markup.link`
  - `@text.uri` -> `@markup.link.url` (in markup links)
  - `@string.special` -> `@markup.link.label` (non-url links)
  - `@punctuation.special` -> `@markup.list` (markdown lists only; move subitems from `@text.todo`)

* Helix captures
  (https://docs.helix-editor.com/master/themes.html#syntax-highlighting):

  - `@method` -> `@function.method`
  - `@method.call` -> `@function.method.call`
  - `@text.{todo,warning,note,danger}` -> `@comment.{error,warning,hint,info,todo}`
  - `@text.diff.{add,delete,}` -> `@diff.{plus,minus,delta}`
  - `@text.uri` -> `@string.special.url` (outside markup)
  - `@preproc` -> `@keyword.directive`
  - `@define` -> `@keyword.directive`(`.define`?)
  - `@storageclass` -> `@keyword.storage`
  - `@conditional` -> `@keyword.conditional`
  - `@debug` -> `@keyword.debug`
  - `@exception` -> `@keyword.exception`
  - `@include` -> `@keyword.import`
  - `@repeat` -> `@keyword.repeat`

* cleanup

  - remove some redundant `@conceal` (but still allow it for conceal-only patterns)
  - remove obsolete `@error` (syntax linting is out of scope for this repo)
  - sort, cleanup capture list in `CONTRIBUTING.md`

1 files changed, 125 insertions, 103 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 209886d54..8c98c46b3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -84,139 +84,145 @@ you can mark the language as optional (by putting it between parenthesis).
 
 As languages differ quite a lot, here is a set of captures available to you when building a `highlights.scm` query. Note that your colorscheme needs to define (or link) these captures as highlight groups.
 
-#### Misc
+#### Identifiers
 
-```scheme
-@comment               ; line and block comments
-@comment.documentation ; comments documenting code
-@error                 ; syntax/parser errors
-@none                  ; completely disable the highlight
-@preproc               ; various preprocessor directives & shebangs
-@define                ; preprocessor definition directives
-@operator              ; symbolic operators (e.g. `+` / `*`)
-```
+```query
+@variable            ; various variable names
+@variable.builtin    ; built-in variable names (e.g. `this`)
+@variable.parameter  ; parameters of a function
+@variable.member     ; object and struct fields
 
-#### Punctuation
+@constant          ; constant identifiers
+@constant.builtin  ; built-in constant values
+@constant.macro    ; constants defined by the preprocessor
 
-```scheme
-@punctuation.delimiter ; delimiters (e.g. `;` / `.` / `,`)
-@punctuation.bracket   ; brackets (e.g. `()` / `{}` / `[]`)
-@punctuation.special   ; special symbols (e.g. `{}` in string interpolation)
+@module            ; modules or namespaces
+@module.builtin    ; built-in modules or namespaces
+@label             ; GOTO and other labels (e.g. `label:` in C), including heredoc labels
 ```
-
 #### Literals
 
-```scheme
-@string               ; string literals
-@string.documentation ; string documenting code (e.g. Python docstrings)
-@string.regex         ; regular expressions
-@string.escape        ; escape sequences
-@string.special       ; other special strings (e.g. dates)
+```query
+@string                 ; string literals
+@string.documentation   ; string documenting code (e.g. Python docstrings)
+@string.regexp          ; regular expressions
+@string.escape          ; escape sequences
+@string.special         ; other special strings (e.g. dates)
+@string.special.symbol  ; symbols or atoms
+@string.special.url     ; URIs (e.g. hyperlinks)
+@string.special.path    ; filenames
 
-@character            ; character literals
-@character.special    ; special characters (e.g. wildcards)
+@character              ; character literals
+@character.special      ; special characters (e.g. wildcards)
 
-@boolean              ; boolean literals
-@number               ; numeric literals
-@float                ; floating-point number literals
+@boolean                ; boolean literals
+@number                 ; numeric literals
+@number.float           ; floating-point number literals
+```
+
+#### Types
+
+```query
+@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)
+@property         ; the key in key/value pairs
 ```
 
 #### Functions
 
-```scheme
-@function         ; function definitions
-@function.builtin ; built-in functions
-@function.call    ; function calls
-@function.macro   ; preprocessor macros
+```query
+@function             ; function definitions
+@function.builtin     ; built-in functions
+@function.call        ; function calls
+@function.macro       ; preprocessor macros
 
-@method           ; method definitions
-@method.call      ; method calls
+@function.method      ; method definitions
+@function.method.call ; method calls
 
-@constructor      ; constructor calls and definitions
-@parameter        ; parameters of a function
+@constructor          ; constructor calls and definitions
+@operator             ; symbolic operators (e.g. `+` / `*`)
 ```
 
 #### Keywords
 
-```scheme
-@keyword             ; various keywords
-@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.return      ; keywords like `return` and `yield`
+```query
+@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.import            ; keywords for including modules (e.g. `import` / `from` in Python)
+@keyword.storage           ; modifiers that affect storage in memory or life-time
+@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`)
 
-@conditional         ; keywords related to conditionals (e.g. `if` / `else`)
-@conditional.ternary ; ternary operator (e.g. `?` / `:`)
+@keyword.conditional         ; keywords related to conditionals (e.g. `if` / `else`)
+@keyword.conditional.ternary ; ternary operator (e.g. `?` / `:`)
 
-@repeat              ; keywords related to loops (e.g. `for` / `while`)
-@debug               ; keywords related to debugging
-@label               ; GOTO and other labels (e.g. `label:` in C)
-@include             ; keywords for including modules (e.g. `import` / `from` in Python)
-@exception           ; keywords related to exceptions (e.g. `throw` / `catch`)
+@keyword.directive         ; various preprocessor directives & shebangs
+@keyword.directive.define  ; preprocessor definition directives
 ```
 
-#### Types
+#### Punctuation
 
 ```scheme
-@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`)
-
-@storageclass    ; modifiers that affect storage in memory or life-time
-@attribute       ; attribute annotations (e.g. Python decorators)
-@field           ; object and struct fields
-@property        ; similar to `@field`
+@punctuation.delimiter ; delimiters (e.g. `;` / `.` / `,`)
+@punctuation.bracket   ; brackets (e.g. `()` / `{}` / `[]`)
+@punctuation.special   ; special symbols (e.g. `{}` in string interpolation)
 ```
 
-#### Identifiers
+#### Comments
 
-```scheme
-@variable         ; various variable names
-@variable.builtin ; built-in variable names (e.g. `this`)
-
-@constant         ; constant identifiers
-@constant.builtin ; built-in constant values
-@constant.macro   ; constants defined by the preprocessor
+```query
+@comment               ; line and block comments
+@comment.documentation ; comments documenting code
 
-@namespace        ; modules or namespaces
-@symbol           ; symbols or atoms
+@comment.error         ; error-type comments (e.g., `DEPRECATED:`)
+@comment.warning       ; warning-type comments (e.g., `WARNING:`, `FIX:`)
+@comment.hint          ; note-type comments (e.g., `NOTE:`)
+@comment.info          ; info-type comments
+@comment.todo          ; todo-type comments (e.g-, `TODO:`, `WIP:`)
 ```
 
-#### Text
+#### Markup
 
 Mainly for markup languages.
 
-```scheme
-@text                  ; non-structured text
-@text.strong           ; bold text
-@text.emphasis         ; text with emphasis
-@text.underline        ; underlined text
-@text.strike           ; strikethrough text
-@text.title            ; text that is part of a title
-@text.quote            ; text quotations
-@text.uri              ; URIs (e.g. hyperlinks)
-@text.math             ; math environments (e.g. `$ ... $` in LaTeX)
-@text.environment      ; text environments of markup languages
-@text.environment.name ; text indicating the type of an environment
-@text.reference        ; text references, footnotes, citations, etc.
+```query
+@markup.strong         ; bold text
+@markup.italic         ; text with emphasis
+@markup.strikethrough  ; strikethrough text
+@markup.underline      ; underlined text (only for literal underline markup!)
 
-@text.literal          ; literal or verbatim text (e.g., inline code)
-@text.literal.block    ; literal or verbatim text as a stand-alone block
-                       ; (use priority 90 for blocks with injections)
+@markup.heading        ; headings, titles (including markers)
 
-@text.todo             ; todo notes
-@text.note             ; info notes
-@text.warning          ; warning notes
-@text.danger           ; danger/error notes
+@markup.quote          ; block quotes
+@markup.math           ; math environments (e.g. `$ ... $` in LaTeX)
+@markup.environment    ; environments (e.g. in LaTeX)
 
-@text.diff.add         ; added text (for diff files)
-@text.diff.delete      ; deleted text (for diff files)
-```
+@markup.link           ; text references, footnotes, citations, etc.
+@markup.link.label     ; link, reference descriptions
+@markup.link.url       ; URL-style links
 
-#### Tags
+@markup.raw            ; literal or verbatim text (e.g., inline code)
+@markup.raw.block      ; literal or verbatim text as a stand-alone block
+                       ; (use priority 90 for blocks with injections)
 
-Used for XML-like tags.
+@markup.list           ; list markers
+@markup.list.checked   ; checked todo-style list markers
+@markup.list.unchecked ; unchecked todo-style list markers
+```
+
+```query
+@diff.plus       ; added text (for diff files)
+@diff.minus      ; deleted text (for diff files)
+@diff.delta      ; changed text (for diff files)
+```
 
 ```scheme
 @tag           ; XML tag names
@@ -224,17 +230,14 @@ Used for XML-like tags.
 @tag.delimiter ; XML tag delimiters
 ```
 
-#### Conceal
+#### Non-highlighting captures
 
-```scheme
-@conceal ; for captures that are only used for concealing
+```query
+@none    ; completely disable the highlight
+@conceal ; captures that are only meant to be concealed
 ```
 
-`@conceal` must be followed by `(#set! conceal "")`.
-
-#### Spell
-
-```scheme
+```query
 @spell   ; for defining regions to be spellchecked
 @nospell ; for defining regions that should NOT be spellchecked
 ```
@@ -243,6 +246,25 @@ The main types of nodes which are spell checked are:
 - Comments
 - Strings; where it makes sense. Strings that have interpolation or are typically used for non text purposes are not spell checked (e.g. bash).
 
+#### Predicates
+
+Captures can be restricted according to node contents using [predicates](https://neovim.io/doc/user/treesitter.html#treesitter-predicates). For performance reasons, prefer earlier predicates in this list:
+
+1. `#eq?` (literal match)
+2. `#any-of?` (one of several literal matches)
+3. `#lua-match?` (match against a [Lua pattern](https://neovim.io/doc/user/luaref.html#lua-pattern))
+4. `#match?`/`#vim-match?` (match against a [Vim regular expression](https://neovim.io/doc/user/pattern.html#regexp)
+
+#### Conceal
+
+Captures can be concealed by setting the [`conceal` metadata](https://neovim.io/doc/user/treesitter.html#treesitter-highlight-conceal), e.g..,
+```query
+    (fenced_code_block_delimiter @markup.raw.block (#set! conceal ""))
+```
+The capture should be meaningful to allow proper highlighting when `set conceallevel=0`. If the unconcealed capture should not be highlighted (e.g., because an earlier pattern handles this), you can use `@conceal`.
+
+A conceal can be restricted to part of the capture via the [`#offset!` directive](https://neovim.io/doc/user/treesitter.html#treesitter-directive-offset%21).
+
 #### Priority
 
 Captures can be assigned a priority to control precedence of highlights via the