Re: Feedback wanted: syntax highlighting in the LilyPond documentation

[Jean Abou Samra]

Le 02/01/2022 à 10:16, Valentin Petzel a écrit :
> Hello Jean,
>
> What I’ve done here is:
>
> 1) Make any macro that has a structural character bold. This helps in quickly
> understanding the basic structure of the document. \tuplet is just a simple
> music function with no real structural importance, so it is not bold. Of
> course it is arguable if something like \relative or \bar should be considered
> as structurally important.


The problem with that is that there are hundreds
of commands. I don't want to decide for each one
if it is structural or not. This is also an issue
of maintainability of the autogenerated list of
builtins. Why not bold for music commands, but then
I think we should use it for all of them.


> 2) Get rid of bright, light highlighting of numbers. Here we might say that
> duration indications are structurally important, so we might handle these
> differently. And of course we can use color for numbers, but it should not
> contrast to much with the surrounding colours (which is mainly black and dark
> blue). See the appended images for an example with a hint of turquoise.


OK, I take note of the turquoise idea (inspired
from Frescobaldi, right?) which looks good. Note
that it's not feasible to highlight numbers differently
from durations since a bare "8" is always taken as a
number (because it's hard to distinguish in
general, e.g. \repeat unfold 8 vs. \skip 8).


> 3) Break up the color of property paths to make them structurally more
> readable. Of course we can color the properties, but we might want to use a
> color that is slightly (but not too much) different from the color for the
> Grob. Again, check out the appended images for an example.

I'm not super keen about this one.  The
idea is to mark that grob properties belong
to grobs and context properties belong
to contexts in an attempt to help the user
get the distinction, so grobs and grob properties
are highlighted the same, and contexts and context
properties ditto. Maybe we could use bold for
grob/context names and non-bold for property
names? (An earlier version did that.)


> I have now also thought that there is no real reason to introduce a whole new
> color for something like \Voice.

Well, it depends on what you call a whole new
color -- it's used on articulations on that
same example, and elsewhere it is the color for
all context names. Can you try the new_style.py
script? That will get you working on a collection
of examples instead of fine-tuning a single one.



[Marc]
> It will be necessary to keep an uncolored version for men (in 
> principle women do not have this problem) who do not see well certain 
> colors.


This is taken care of -- the colors have been
chosen to have enough contrast to the white
background to be readable even for those
with impaired vision. Since I am not such a
person, I have been checking the scheme against
WCAG recommendations. The color with least
contrast has 6.15, which is quite a bit
above the WCAG AA level of 4.5. This means that
even someone not discerning colors at all
can read such highlighted code.


[ebenezer]
> Hi Jean,
>
> I like the idea that it should be possible.
>
> I would like for it to be (easily) customisable.


Well, it is built in a customizable way, see
the reply above to Calvin. The technique is
the same as to change the highlighting on,
say, Wikipedia.


> I already have a text editor colour scheme that I use for music, for 
> parts and scores I have found it is not so important.
>
> My perspective is that I only need colour for highlighting key items 
> within music such as \time, \tempo, comments, \override, bar lines and 
> 'beat space'; beat space is 2 white spaces that I use to delineate 
> music within a measure, I find having this as bright white on a pale 
> silver background really helps.


That's a bit tricky because the lexer doesn't recognize
double spaces specially. The customizability you get
is on the colors used for the different categories, not
on the classification itself. However, this is not
really a problem here because the LilyPond
documentation does not use this convention of
double spaces. If you want to use the highlighting
in your own documents, see
https://lists.gnu.org/archive/html/lilypond-user/2021-11/msg00418.html
You can tweak the lexer by subclassing it in Python, read
https://pygments.org/docs/lexerdevelopment/#subclassing-lexers-derived-from-regexlexer
for how to do that. (But be prepared to discover
that recognizing LilyPond syntax is not as easy
as it might seem.)


> Thank you for throwing this out there, and sorry that you will have 
> 1001 conflicting opinions on how to progress!


I already have. :-)


> Good luck.


Thanks!


Jean