Less subtle syntax highlighting of class 3 keywords

[henrikt-ma]

I'm sorry to bring up the question about syntax colors in listings once more, but having spent some time with the new color of class 3 keywords (der, Real, etc), I find the brown too subtle. It doesn't pop out too much when used in inline listings (like the old red color did), which is an improvement, but it has become too similar – at least to my eyes – to the un-highlighted black. If anything, it just looks de-highlighted:

I find the problem being exaggerated when viewing at low magnification, like when reading on my phone.

Maybe this isn't a big deal, but I feel responsible to bring it up because I was driving the change from the old popping-out-red to the current de-highlighted-brown.

To improve the situation, I've come to the conclusion that the green color serves better as a keyword color than as comment color, as green doesn't pop out too much to be used in inline listings. Comments, on the other hand, are rarely seen in inline listings, and can therefore use colors that would pop out too much when used in inline listings. I chose a color called plum which I found to both give good contrast and clear separation from non-comment code.

With both blue and green tones working well in inline listings, I find that blue is more similar to black, and that it therefore makes most sense to apply this to keyword class 3, meaning that green would be used for the actual keywords.

With this reasoning, the excerpt above turns into this:

This PR is opened in Draft state both to indicate that the proposed colors are something I expect to raise reactions that will require adjustments, but also because I'd like to also include updated figures before merging.

[henrikt-ma]

In case plum colored comments make the document look too colorful, a dark orange could be a nice alternative:

\definecolor{commentcolor}  {rgb}{0.70, 0.41, 0.00}

Personally, I prefer the plum because its hue somehow gives it good sensation of contrast without having to be so dark that it's almost black.

[henrikt-ma]

Also making string literals slightly lighter than black for improved readability. For example, I find that this makes it much easier to separate a description string from the rest of a component declaration, making it easier to quickly find the various parts of a declaration:

This gray is dark enough to not look disturbingly washed out when appearing in inline listings.

[HansOlsson]

I think I prefer the green for comments, but I don't really see how to make the dark-red more visible at the moment.

One reason is that it is common highlighting in tools for other languages.

[HansOlsson]

I think I prefer the green for comments, but I don't really see how to make the dark-red more visible at the moment.

One reason is that it is common highlighting in tools for other languages.

To clarify my comment: I meant that green is common for comments in tools for other languages, and thus I would prefer to keep that. (And blue for keywords as well.)

[henrikt-ma]

I think I prefer the green for comments, but I don't really see how to make the dark-red more visible at the moment. One reason is that it is common highlighting in tools for other languages.

To clarify my comment: I meant that green is common for comments in tools for other languages, and thus I would prefer to keep that. (And blue for keywords as well.)

I won't go into debate about what is common, but plan to return to this shortly to see what can be done.

[henrikt-ma]

To clarify my comment: I meant that green is common for comments in tools for other languages, and thus I would prefer to keep that. (And blue for keywords as well.)

While I find it marginally interesting to compare with what is common in other languages, why don't we just have a look at default syntax highlighting in Modelica tools? Maybe that could be a source of inspiration…

I prepared a small model to this end:

model HighlightedSyntax
  type Enum = enumeration(one, two, three) "User-defined enumeration";

  function foo "User-defined function"
    input Enum e;
    output Real y = if e == Enum.one then 1.0 else 0.0;
  end foo;

  constant Real delta = 4.669 "Feigenbaum's first constant";
  final parameter Real p = 1.0 annotation(Evaluate = false);
  Real x(stateSelect = StateSelect.prefer);
  Modelica.Blocks.Sources.Sine source(freqHz = 5);
  Modelica.Blocks.Continuous.Integrator speed;
initial equation
  p * x = delta;
equation
  when {initial(), edge(delta > 4.5)} then
    assert(pre(x) > 0, "Bad initialization of x.");
  end when;
  der(x) + sin(x) = speed.y * foo(Enum.two); /* Much better than the equation below. */
//der(x) = cos(x);
  connect(source.y, speed.u);
end HighlightedSyntax;

This is what it looks like in System Modeler (let's not discuss any details):

@HansOlsson, @gkurzbach, @sjoelund, @eshmoylova, @axelmartenssonmodelon, and others, you are invited to supply screen shots of the default syntax highlighting in your tools!

[beutlich]

Dymola in dark mode:

SimulationX:

[HansOlsson]

The red in Dymola is for using class and function names (including operators and built-in classes); and as seen we use the same green for comments and strings.

Notes:

• You can override these colors in generated html etc using css (separate for function names and classes, and separate for comments and strings).
• If you paste the entire text it you have to use "Ctrl-L" (highlight syntax) to get all of it.

[sjoelund]

OMEdit:

[HansOlsson]

OMEdit:

This seems a bit confusing, is the blue color intended for things that are seen as function calls?

[sjoelund]

This seems a bit confusing, is the blue color intended for things that are seen as function calls?

I guess so. @adeas31 created the GUI :)

[henrikt-ma]

OMEdit:

This seems a bit confusing, is the blue color intended for things that are seen as function calls?

There are probably things that several of us dislike about each of the provided samples, but maybe we don't need to talk so much about the things we don't like, and shift focus to identifying the more or less common approaches that we like…

For example, I get the sense that OMEdit has a certain color for keywords, which I like (even though having several categories could have improved readability further). The sample also shows that OMEdit adheres to the popular philosophy of comments in a friendly and highly visible green.

[HansOlsson]

OMEdit:

This seems a bit confusing, is the blue color intended for things that are seen as function calls?

There are probably things that several of us dislike about each of the provided samples, but maybe we don't need to talk so much about the things we don't like, and shift focus to identifying the more or less common approaches that we like…

I was just trying to confirm that I understood the logic.

For example, I get the sense that OMEdit has a certain color for keywords, which I like (even though having several categories could have improved readability further). The sample also shows that OMEdit adheres to the popular philosophy of comments in a friendly and highly visible green.

So, if we look at categories we have:

Category	Dymola	SimulationX	OMEdit	System Modeler
Strings	Green	Dark Red	Green	Italic light red
Comments	Green	Green	Green	Italic light red
Keywords	Blue	Blue	Dark red	Green,Pink
Function calls	Red	Blue	Green	Blue
Classes	Red	Black	Black	Black
Builtin Classes	Red	Red	Red	Pink
Numbers	Black	Black	Green	Black
Default	Black	Black	Green	Black

So, I agree that OMEdit uses green for comments - and also the same color for strings (as Dymola); I believe part of that is that the strings after a declaration are sort of strings and sort of comments - so I can see reasons to have the same color for both.

[henrikt-ma]

So, if we look at categories we have: …

The table looks a bit over-simplified (but might be of some use nevertheless)

• System Modeler doesn't color functions being called in general, see call to foo. However, it adds color to (at least some of) the functions from the language specification.
• Several tools don't apply the same color to the two predefined types Real and StateSelect (but System Modeler does).
• Dymola doesn't color classes red in all cases, such as in Enum.two. Rather, it seems to use red for the type of a component declaration, a kind of context-sensitivity that isn't seen in other tools.

So, I agree that OMEdit uses green for comments - and also the same color for strings (as Dymola); I believe part of that is that the strings after a declaration are sort of strings and sort of comments - so I can see reasons to have the same color for both.

Yes, having the same color for description strings and comments would be nice if it wouldn't make all strings look like comments. This could be done using the kind of context sensitivity seen in Dymola, but doesn't seem doable with listings.sty.

[sjoelund]

So, I agree that OMEdit uses green for comments - and also the same color for strings (as Dymola); I believe part of that is that the strings after a declaration are sort of strings and sort of comments - so I can see reasons to have the same color for both.

Yes, and the Qt built-in syntax highlighter is a quite basic thing, so it's hard to distinguish class comments from expressions. If we're using the LaTeX listings package, we will have even more limitations than the Qt lexer as far as I know.

If we were using minted, we could have more advanced highlighting. But it didn't work in latexml, right?

[HansOlsson]

So, I agree that OMEdit uses green for comments - and also the same color for strings (as Dymola); I believe part of that is that the strings after a declaration are sort of strings and sort of comments - so I can see reasons to have the same color for both.

Yes, and the Qt built-in syntax highlighter is a quite basic thing, so it's hard to distinguish class comments from expressions. If we're using the LaTeX listings package, we will have even more limitations than the Qt lexer as far as I know.

Yes, and I was also thinking of the user-experience. Even if we can explain that those description strings are kind of like comments, but still strings (or the other round depending on what we want) I think it becomes too overwhelming.

[henrikt-ma]

Yes, and I was also thinking of the user-experience. Even if we can explain that those description strings are kind of like comments, but still strings (or the other round depending on what we want) I think it becomes too overwhelming.

I'm trying to also keep the appearance in inline listings in mind, and then I don't think that the friendly and highly visible green would look good at all when used for the strings that are most likely to appear in inline listings (that is, anything but description strings), such as "External", "ImplicitEuler", "Colors.red", "FORTRAN 77", "linux64", "kg.m/s2", "Vehicle.engine.controller"…

[eshmoylova]

MapleSim:

It is also probably important to try to make it as color-blind-friendly as possibly. Usually, color blind people cannot distinguish between reds and greens, and occasionally blues. It might be good to additionally use bold and/or italic.

[henrikt-ma]

Way too many unnecessary changes to evaluate at the moment.

Are you sure? The diff is quite minimalistic.

On the other hand, I would suggest putting this on hold while we work on #2785, as that currently contains a change of font that makes the class 3 keywords look lees washed out:

[HansOlsson]

Way too many unnecessary changes to evaluate at the moment.

Are you sure? The diff is quite minimalistic.

The diff in terms of commit-changes is minor, but the impact on the result is too large - and looking at the pdf https://test.openmodelica.org/jenkins/job/ModelicaAssociation/job/ModelicaSpecification/view/change-requests/job/PR-2790/lastSuccessfulBuild/artifact/MLS.pdf the result is not as shown above; which makes it even more confusing.

[gkurzbach]

Looking at this:

it looks quit good for me.

[HansOlsson]

Looking at this:

it looks quit good for me.

I agree, but looking at https://test.openmodelica.org/jenkins/job/ModelicaAssociation/job/ModelicaSpecification/view/change-requests/job/PR-2790/lastSuccessfulBuild/artifact/MLS.pdf I instead see (sorry about the selection):

which I don't think look good at all.

[henrikt-ma]

which I don't think look good at all.

Yes, and this is part of the reason why I think revisiting this PR after #2785 would be a better idea. The current state of the present PR is that it got stuck in collection of input from tool vendors, and considering the diverse input to the discussion I wouldn't be surprised if we end up concluding that what we get from #2785 is good enough for now.

[HansOlsson]

which I don't think look good at all.

Yes, and this is part of the reason why I think revisiting this PR after #2785 would be a better idea.

I agree that it makes sense to wait. When we return to this one we must ensure that we are looking at the result of the actual pull request to avoid confusion.

[henrikt-ma]

I'm ready to give up on seeking agreement on any change of colors. I guess I'm getting used to the washed-out look of those light brown identifiers… Anyone interested in bringing this discussion back to life?

[HansOlsson]

I'm ready to give up on seeking agreement on any change of colors. I guess I'm getting used to the washed-out look of those light brown identifiers… Anyone interested in bringing this discussion back to life?

Doesn't seem so. It has now been close to two years without any action, so I think it may be best to close this and restart a new PR if needed.

[henrikt-ma]

OK, giving up. Closing.