Description
A user has reported that they found the reference pages confusing because the syntax 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, 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 Reference website colours no longer correct #820