teaboy
August 16, 2019, 9:44am
1
Please excuse a "dummy" question. I have been trying to understand the use of text colours in sketch text.
If I look in the reference section I see that functions are coloured orange, variables are turquoise green and structure text is olive green.
If I click on, for example "if" (olive green) it brings up the the explanation of the syntax and example text which is coloured orange
Am I missing something obvious?
Alan
pert
August 16, 2019, 9:57am
2
It's not clear to me what you're asking. Are you talking about the fact that the coloration in the reference pages does not match the coloration in the Arduino IDE. That is indeed unfortunate, and it has been reported to the Arduino developers already:
opened 08:58AM - 07 May 19 UTC
A user has reported that they found the reference pages confusing because the sy… ntax highlighting colors don't match those of the Arduino IDE.
Example code rendered at https://www.arduino.cc/reference/en/language/structure/control-structure/for/
The same code as shown in the Arduino IDE with the default theme:
---
---
The issue reported is that keywords like `setup`, `loop`, and `for` are colored orange in the reference, but are colored a dark olive green in the Arduino IDE. This misled the user into thinking that the Arduino IDE was not working properly.
The coloration in the IDE is periodically reported on the Arduino Forum by beginners who think that keywords not turning orange is an indication that something is wrong. The dark olive green color is close enough to the black of regular text that they don't notice these keywords are being colored. This is the first time I've learned of this confusion being connected to syntax highlighting colors on the reference pages, so I don't know whether that was a factor in any of the other reports.
I don't know what system Arduino uses to render the Language Reference's asciidoc on arduino.cc so I haven't been able to investigate whether there is any possibility of doing something about this. The `setup`, `loop`, and `for` keywords are defined in a global keywords.txt file:
https://github.com/arduino/Arduino/blob/master/build/shared/lib/keywords.txt
Each library also has its own keywords.txt file, where keywords specific to that library are defined. The only library documentation contained in the Arduino Language Reference is for the Keyboard and Mouse libraries. Their keywords.txt files are here:
- https://github.com/arduino-libraries/Keyboard/blob/master/keywords.txt
- https://github.com/arduino-libraries/Mouse/blob/master/keywords.txt
Coloration of keywords is defined in theme.txt:
https://github.com/arduino/Arduino/blob/master/build/shared/lib/theme/theme.txt
and documented in the Library Specification:
https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#keywordstxt-format
The theme system has become quite convoluted and it is not immediately obvious how it works. Let's take `for` as an example:
https://github.com/arduino/Arduino/blob/master/build/shared/lib/keywords.txt#L307
```
for KEYWORD3 For RESERVED_WORD
```
Since it uses the `KEYWORD3` `KEYWORD_TOKENTYPE`, you might think that the `editor.function.style` property would apply and thus it would be colored according to:
https://github.com/arduino/Arduino/blob/master/build/shared/lib/theme/theme.txt#L98
```
editor.function.style = #d35400,plain
```
However, when using any IDE version 1.6.5 or newer (which we should assume the user is), `RSYNTAXTEXTAREA_TOKENTYPE` overrides `KEYWORD_TOKENTYPE`, if defined. Thus, the `editor.reserved_word.style` property applies instead and `for` is colored according to:
https://github.com/arduino/Arduino/blob/master/build/shared/lib/theme/theme.txt#L102
```
editor.reserved_word.style = #5E6D03,plain
```
This issue also occurs on the [Tutorial pages](https://www.arduino.cc/en/Tutorial/HomePage), but I notice those have different coloration than the Language Reference pages, so I suspect there is a different syntax highlighting system used there.
---
### References
- At least somewhat related to https://github.com/arduino/reference-en/issues/820
One thing you should know about the syntax coloration in the Arduino IDE for libraries is it is accomplished via a very crude system. Library authors can define keywords for their libraries. Some do this, others don't bother, some do it incorrectly, others do it but don't maintain their keywords list so only some of the functions of that library are colored. The Arduino IDE will color all the keywords of every library you have installed, even the libraries you're not using in your sketch. This means that once you get a lot of libraries installed you'll end up with many random words in your sketch colored.
So don't put so much meaning into the colors of text in the Arduino IDE