[vim/vim] Unclear documentation on `syntax reset` vs. `highlight clear` (Issue #11750)
Dani Dickstein
Steps to reproduce
The documentation for highlight clear says "Reset all highlighting to the defaults." while the documentation for syntax reset says "If you have changed the colors and messed them up, use this command to get the defaults back...it only affects the highlighting." So if you want to reset highlighting to vim's defaults, which command should be used? Does one of them imply the other? And what is the best practice for color scheme definitions? There's also syntax clear, which is supposed to be called "when you want to switch to using another syntax," so for a color scheme definition that also seems like a good line to add, but seems like it may obviate the others?
Expected behaviour
Clarify documentation around these 3 commands in particular to emphasize the circumstances under which each should be called.
Version of Vim
9.0
Environment
Operating system: Linux
Terminal: xfce4-terminal 1.0.4
Value of $TERM: tmux-256color
Shell: bash 5.1.16
Logs and stack traces
No response
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Bram Moolenaar
> The documentation for `highlight clear` says "Reset all highlighting to
> the defaults." while the documentation for `syntax reset` says "If you
> have changed the colors and messed them up, use this command to get the
> defaults back...it only affects the highlighting." So if you want to
> reset highlighting to vim's defaults, which command should be used?
highlighting and defining colors for highlight groups. You should
probably read further back from those commands to understand the context.
> Does one of them imply the other? And what is the best practice for
> supposed to be called "when you want to switch to using another
> syntax," so for a color scheme definition that also seems like a good
> line to add, but seems like it may obviate the others?
to the start of the help section to understand what they are for.
--
Vi beats Emacs to death, and then again!
http://linuxtoday.com/stories/5764.html
/// Bram Moolenaar -- ***@***.*** -- http://www.Moolenaar.net \\\
/// \\\
\\\ sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Dani Dickstein
Ah I think I got confused when I was reading the documentation for syntax clear. If I'm understanding that one correctly it applies to syntax rules, not highlighting rules, and clears them for the current buffer. I gather that it leaves all highlighting rules intact, for example:
syn keyword myfoo foobar
hi myfoo guifg=green
" at this point, foobar will be highlighted in green
syn clear
" at this point foobar will not be highlighted because the syntax rule is cleared for the buffer
syn keyword myfoo foobar
" at this point foobar will be highlighted green again (the highlight rule wasn't cleared)
Ok so leaving syntax clear out of the picture, I think I'm unclear on syntax reset vs. highlight clear, which both appear to affect highlighting rules.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Jordan Torbiak
@ddickstein I've had similar confusion about syntax highlight for years and finally dug into it. :hi clear and :syntax reset both deal with highlight groups, but they affect different sets of groups. In src/highlight.c or :help hightlight-groups, you can see the highlight groups that the default colorscheme defines: Normal, Search, StatusLine, Visual, etc. And in runtime/syntax/syncolor.vim or :help group-name, you can see the default syntax-related highlight groups that get defined: Comment, Constant, Identifier, Statement, etc. Also, recall that syntax highlighting works by making syntax groups that match patterns in a buffer, and then :hi link {syntax-group} {highlight-group} links that syntax group to a highlight group that defines the colors to use.
With that in mind, here's what those commands do:
:hi clear: clear all highlight groups, reload the current colorscheme, and dosyntax on.:syntax on: load the default syntax-related highlight groups, except that if a group that is linked by default currently has non-link settings, those settings are kept.:syntax reset: load the default syntax-related highlight groups, including any that are linked by default but currently have settings.:syntax clear: clear all the syntax groups for the current syntax (c,help,python, etc). Doesn't affect highlight groups.
Since :hi clear clears all the highlight groups, it doesn't matter if it does :syntax on or :syntax reset: they'd both have the same effect.
Some more detail: :hi clear calls highlight_reset_all(), which clears all the highlight groups and then calls init_highlight() to recreate the defaults. init_highlight() creates the default colorscheme groups then sources syncolor.vim with the implicit on command (almost equivalent to :syntax on) to create the syntax-related highlight groups.
When loading a colorscheme, I'd want to reload all of the default highlight groups, which :hi clear does. Before v9.1 all the builtin colorschemes did a :syntax reset if syntax highlighting is enabled, but that doesn't seem necessary, and the colortemplate-generated themes in v9.1+ no longer do it. $VIMRUNTIME/colors/README.txt is the doc about how to write colorschemes (linked from :help color-schemes), and it says to just use :hi clear.
Now that I have a better understanding of everything, the docs for these commands and syntax highlighting in general (:help syntax) seem quite clear, but I can definitely empathize with it being confusing before knowing how syntax and highlight groups relate and what the default ones are.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Scott Leggett
@torbiak that's one hell of an explanation. Thanks!
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.