Thx to @romainl, @neutaaaaan

Codecov Report

Merging #12163 (185b2a2) into master (1433802) will decrease coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #12163      +/-   ##
==========================================
- Coverage   81.95%   81.95%   -0.01%     
==========================================
  Files         160      164       +4     
  Lines      193810   194090     +280     
  Branches    43840    43830      -10     
==========================================
+ Hits       158834   159059     +225     
- Misses      22138    22198      +60     
+ Partials    12838    12833       -5     

Flags with carried forward coverage won't be shown. Click here to find out more.

see 46 files with indirect coverage changes

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

Just a heads-up : this commit doesn't touch CODEOWNERS and CODEOWNERS is currently lacking entries for the habamax, lunaperche, and quiet colorschemes that already ship with the runtime.
They need to be added to CODEOWNERS, along with the new colorschemes zaibatsu, wildcharm, sorbet and retrobox

Hmm, speaking of CODEOWNERS, GitHub doesn't seem to like how it is used:

@brammool @chrisbra, the doc clearly says that it should contain the names of people with write permissions, which is clearly not the case for most people in that file.

Are they notified anyway, even if they are outsiders?

yeah I have noticed in the past and wondered if it really helps. You could test it out by creating a dummy PR against e.g. runtime/colors/blue.vim and see if you get notified.

But even if this doesn't work, it at least is (yet another) way to know whom to notify

About the colorschemes: Any comments on including these? I like to keep the number of distributed colorschemes small, so that users are not overwhelmed. They should be quite different.

About CODEOWNERS: I don't know why github requires write access. Is that configurable somewhere?

I've noticed an inconsistency between a few colorschemes. Some colorschemes contain highlight groups that are defined by 3rd party plugins (e.g. fugitive, ALE, etc.), or syntax files (e.g. vimOper, elixirOperator, javaScript*, etc.), while others don't. Is that by accident? IMO, all distributed colorschemes should provide the same highlight groups.

Should filetype-specific highlight groups like vimOper, elixirOperator etc. even be defined in a colorscheme? If this becomes a common theme, the colorschemes will grow very quickly once users start adding filetype-specific highlight groups to each colorscheme (there are over 500 different syntax files, each one defining several syntax groups). I can understand the reasoning behind it but I feel like they will quickly become unmaintainable.

I thought the purpose of a colorscheme file was to define only general highlight groups (like :h highlight-default and :h group-names).

@bfrg Yes, the fact that some have those specific groups and some don't is definitely an accident. I agree, non-default highlight groups have nothing to do here.

@habamax can we talk about lunaperche and habamax?

Sure, we can, @romainl. Let's remove it, though it wouldn't be the colorschemes I, as an author, aimed to create anymore.

They should be quite different

@brammool while the work done last year indirectly did a lot to improve variety between the older colorschemes, most of them use rather aggressive or dull colors, with little thought given to the overall balance and feel. This cannot be fixed without drastically altering them, much beyond what we already had to do to ensure they'd behave properly in different environments.

This is the main reason why retrobox, sorbet, zaibatsu and wildcharm (as well as quiet, habamax and lunaperche, that already ship as part of the runtime) exist. Those newer colorschemes are based on styles popular within the larger vim colorscheme ecosystem in terms of palette and general feel, and aim to round out the current set of colorschemes.
And as they are specified rather exhaustively, it's viable for an end user to pick one and, through the use of autocommands, use it as a "platform" for their own modifications, without having to understand too much about colorschemes, or being forced to shlep many files around.

FWIW, Operator is linked to Statement in syntax/syncolor.vim and linked to in 480+ places under syntax/.

In my opinion, everything under :help highlight-groups is fair game, as well as any other group that is used by Vim out of the box, without necessarily being documented in that section. Like… the following list, taken from syntax/syncolor.vim:

SynLink String		Constant
SynLink Character	Constant
SynLink Number		Constant
SynLink Boolean		Constant
SynLink Float		Number
SynLink Function	Identifier
SynLink Conditional	Statement
SynLink Repeat		Statement
SynLink Label		Statement
SynLink Operator	Statement
SynLink Keyword		Statement
SynLink Exception	Statement
SynLink Include		PreProc
SynLink Define		PreProc
SynLink Macro		PreProc
SynLink PreCondit	PreProc
SynLink StorageClass	Type
SynLink Structure	Type
SynLink Typedef		Type
SynLink Tag		Special
SynLink SpecialChar	Special
SynLink Delimiter	Special
SynLink SpecialComment	Special
SynLink Debug		Special

or debugPC and debugBreakpoint, which are underdocumented.

Sure, we can, @romainl. Let's remove it, though it wouldn't be the colorschemes I, as an author, aimed to create anymore.

That's precisely why I won't submit Apprentice or Malotru for inclusion.

I've mentionned that during a private conversation with @habamax already, but I think getting rid of all the custom links is a bad idea.
Anything that ships with the runtime is fair game in my opinion, and if some elements end up being highlighted in a way that feels semantically misleading, and the issue isn't clearly with the syntax file itself, then this ought to be fixed in the colorscheme.

There will always be such instances of awkward highlighting because of design decisions that work perfectly fine in the context the author was initially thinking about, but don't pan out when editing specific filetypes.
Shell scripts will never not look like a clown got food poisoning. DiffRemoved inherits its color from the Special group for some reason, but there's no guarantee of Special being red.
Those discrepancies and issues just pile up as more work goes into refining a colorscheme. It's unavoidable.

Some of the older colorschemes rewire minor groups pretty liberally. I can only assume this is because the original authors had similar issues within the small subset of filetypes they worked with. This shouldn't have been allowed to happen.
Case by case overrides is the only way to address this.

DiffRemoved inherits its color from the Special group for some reason, but there's no guarantee of Special being red.

I think you're talking about diffRemoved which is defined in syntax/diff.vim. And I agree, this syntax group is an exception. Most users will expect a red foreground. It is different from DiffRemoved which is used in diff-mode where most users will expect it to have a red background. I'm sure there are more exceptions where neither of the highlight groups mentioned in :h group-names fit well. Maybe that list should be extended?

Currently, there are 5 different group names for the Preprocessor. Most colorschemes I've seen use the same color for all 5 groups. Likewise, there are different group names for for/while loops, conditionals, labels and exceptions. The colorschemes I've seen will all highlight them as Statement. But then, on the other hand, there is only Underline. Where is Bold and Italic? Similarly, there's one highlight group called Error, but Warning and Info are missing. Maybe a few more group names could be added so that syntax files can link to them? OTOH, html and many doc file like markdown, rst, asciidoc, latex etc. use different headings. html uses h1 to h6, the other formats use something similar. But Vim provides only one highlight group that is useful and that is Title. A few more default names could be added. Then other syntax files could link against them and colorschemes would adopt these names.

Most other highlight groups that I can see, for example, in the colorscheme habamax, I would expect them to be defined in after/syntax/<filetype>.vim. For example:

hi! link javaScriptFunction Statement
hi! link javaScriptIdentifier Statement

I use the exact same javascript links. But since I want this behavior for every colorscheme, I have put these links in after/syntax/javascript.vim.

I really wonder how other editors solve all this.

That's precisely why I won't submit Apprentice or Malotru for inclusion.

@romainl Is Apprentice broken when you remove certain links? Maybe after/colors/<colorscheme>.vim should be automatically sourced once a specific colorscheme is loaded, similar to after/ftplugin/<filetype>.vim? I know this is already possible with autocommand and the ColorScheme event but working with files is easier and it is already done for filetype and syntax files.

Some housekeeping would be nice, but more groups would not help this particular situation, as overrides would inevitably happen regardless. Colorschemes are as much about aesthetics as they are about shaping up your interpretation of the underlying semantics.

Similarly, I don't see how throwing more files into the runtime to handle the exceptions could help. That's just shuffling the solution around for the sake of correctness, whilst making the whole thing harder to grasp for an end user.

I'll include this now, as there are no relevant objections. There are always remarks about what looks good or bad to some users. We will keep improving this over time.