search

RRethy / vim-illuminate

illuminate.vim - (Neo)Vim plugin for automatically highlighting other uses of the word under the cursor using either LSP, Tree-sitter, or regex matching.
2.12k stars 44 forks source link

Request clarification in documentation for #165

Closed unphased closed 1 year ago

unphased commented 1 year ago

Describe the bug In the help and readme, it says:

==============================================================================

  1. Highlight Groups illuminate-highlight-groups

ILLUMINATEDWORDTEXT

Default highlight group used for references if no kind information is available.

hi def IlluminatedWordText gui=underline

ILLUMINATEDWORDREAD

Highlight group used for references of kind read.

hi def IlluminatedWordRead gui=underline

ILLUMINATEDWORDWRITE

Highlight group used for references of kind write.

hi def IlluminatedWordWrite gui=underline

It's not clear what this means. What is a read/write "kind" of reference?

unphased commented 1 year ago

Simple testing reveals that the highlights correspond to whether a given symbol/variable/token is being set or read. something like that. So i'll close, but the documentation needs improvement IMHO.

fent commented 8 months ago

after reading that, i still don't understand :/

unphased commented 8 months ago

i noticed this only really works on very few languages. basically this plugin uses treesitter to differentiate between when a given highlighted symbol is in a "read" context or a "write" context.

For example when you assign a variable e.g. let x = "42" and you put your cursor on some later reference to x, the style you gave IlluminatedWordWrite will be applied to the x in the assignment statement but not to the other references of it. Make sense?

I find very little value in this because it only works on like 2% of languages in my experience -- probably only ever seen it work for lua. And if it's not gonna work everywhere then you can't count on it to help you. You may as well not assign these highlight styles since they will by default link to the Text one I think.

RRethy commented 8 months ago

Some languages have an LSP or treesitter queries which differentiate read/write, others just use text because it's easier. It's not up to vim-illuminate, but we will interpret them appropriately if they are available. As OP said, it's rare they are implemented.