Re: RFC: Adding syntax highlighting to the official documentation

[Mats Bengtsson]

   Thanks for your work on this! A couple of comments (sorry, I haven't
   taken the time to look and comment on your proposal earlier):

   - I cannot see that you explain to the user what syntax classes the
   different colors correspond to. It could of course be seen as a
   pedagogical trick to let the readers figure out the system themselves,
   and thereby learning more about the syntax, but I guess that many
   readers would just get confused or perhaps irritated if they try to see
   a pattern and don't really get it. Such an explanation could be done in
   two ways, either in the LM by introducing each color in parallel with
   the introduction of the corresponding syntactic class, or as a brief
   list aimed at the readers who already know the syntax. Ideally, we
   could have both of these.

   - On a page like
   [1]http://abou-samra.fr/new-highlighting-demo/notation/the-offset-comma
   nd.html, there are boxes where the syntax is defined, but in those
   there's no syntax highlighting, in contrast to the full examples. How
   difficult would it be to add syntax highlighning also within these
   blocks, generated from
   @example ... @end example in the .texi code?

      /Mats

   On 2022-01-30 19:52, Jean Abou Samra wrote:

     Hello everyone,
     The syntax highlighting patch is back. I have pushed the
     latest version to the GitLab MR (as a reminder, this is
     [2]https://gitlab.com/lilypond/lilypond/-/merge_requests/1019).
     You can find the new demo here:
     [3]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

References

   1. 
http://abou-samra.fr/new-highlighting-demo/notation/the-offset-command.html
   2. https://gitlab.com/lilypond/lilypond/-/merge_requests/1019
   3. http://abou-samra.fr/new-highlighting-demo/notation/index.html