Re: RFC: Adding syntax highlighting to the official documentation

[Jean Abou Samra]

Hello everyone,

The syntax highlighting patch is back. I have pushed the
latest version to the GitLab MR (as a reminder, this is
https://gitlab.com/lilypond/lilypond/-/merge_requests/1019).
You can find the new demo here:

http://abou-samra.fr/new-highlighting-demo/notation/index.html

Perhaps the most important change is the addition of a
toggle to turn highlighting on and off. This is a link
at the bottom of each page, which shows "Disable syntax
highlighting" (and morphs into "Enable syntax highlighting"
when you click it). Next to it, there is "Save syntax
highlighting preference" which has the effect of saving
the current setting in the browser so that other documentation
pages and subsequent visits use the same setting (after
displaying a legalese for compliance with the EU ePrivacy
directive, also known as cookie law). I hope this will
leave those not liking syntax highlighting satisfied.
Thanks to Aaron for his assistance with JavaScript
programming.

Also, while I have done my best to accomodate different
wishes and directions in the highlighting scheme, this
is not always possible. It was a good thing to ask on
lilypond-user, as this has yielded several good ideas.
Nevertheless, at some point we have to move on. I intend
the latest scheme to be more or less definitive, i.e.
if you like it but would like some small adjustments,
they can be done, but on the other hand if you don't
like it at all, you may be better off with the 'Disable
syntax highlighting' button, or alternatively, a style of
yours that you can either keep local or later integrate
in the official documentation as an option next to
the 'Disable syntax highlighting' and 'Save syntax highlighting
preference' links.

Another noteworthy change is that I have increased
the font size of code samples a bit in order to accomodate
for the loss of contrast inherent to syntax highlighting.
Note also that the contrast has been improved, see below.

Apart from these general changes, the style has evolved
on some aspects. Attached is the comparison of this new
(third) style to the older (second) style (if you have
not followed the whole discussion, these two styles are
both vastly different from the first style proposed at
the very beginning). The sample is the same that was
next to the new_style.py script. (Sorry that there is
no comparison for the full demo on abou-samra.fr, the whole
thing is too large for two copies to fit given size limits
on the server). These are the main "highlights":

* For more readability, the colors have been adjusted to be
  darker and more pronounced, particularly the blue.

* The fragile distinction between keywords and music functions
  is no longer attempted. They are now all blue. Note that
  this also means there is no bold at all anymore for "pure-LilyPond"
  code, only for important builtins like let and map in Scheme code.

* Scheme functions defined by LilyPond are now blue as well. This
  is consistent with the fact that LilyPond's music functions
  can equally be called as functions from Scheme, and makes
  functions more discrete in long Scheme code samples.

* Pitches are now turquoise, following a suggestion from Valentin.

* Repeat types are no longer highlighted specially.

* Since markups are a kind of extension of strings
  (or at least, strings are a special case of markups),
  they are now the same color as strings (yellowish).

I believe this is starting to be about ready for inclusion.

Best regards,
Jean

style-comparison.tar.gz
Description: application/gzip