Re: Feedback wanted: syntax highlighting in the LilyPond documentation

[Jean Abou Samra]

Le 04/01/2022 à 00:33, David Kastrup a écrit :
> Flaming Hakama by Elaine <elaine@flaminghakama.com> writes:
>
> > In this sense, it seems like the place that has the most potential use
> > for helping people distinguish different data types is where the
> > syntax is the most complicated and dense, which is in music entry.
> >
> > The ability to quickly distinguish articulations, dynamics, notes, and
> > durations seems like it would probably be most useful to people
> > reading examples in docs, since that is the most unusual aspect of
> > lilypond syntax.
> I find splitting a8 into different colors about as helpful for reading
> music as coloring note stems differently would be for reading score
> sheets: there is a standard place they are attached to anyway and there
> is no particular reason to look elsewhere.


Highlighting \breve and \longa is useful in my view
because it clarifies that they are not articulations
as their syntax might suggest.

And then there is still the problems that durations
are not recognized from numbers in general. I don't
have a whole lot of time this week; still have to
see if it looks good not to highlight any numbers
at all.



> It would be much more useful to highlight note lengths separated by
> space but still common to a preceding note or rest, like
>
> \drummode { bd4 r r 4. 8 }
>
> where the 4. is sucked into the second r likely unintentionally.
> Highlighting this is helpful.


Then we are not talking about the same use cases
for highlighting. But while this might be helpful
in an editor, I don't see the relevance for
documentation. The goal is to help the reader,
not the documentation writer. Whether the input is
intentional or not -- and it should really be
for documentation --, focusing the reader's
attention on that is inappropriate. Not to mention
that \func a 8 where \func is some builtin or custom
function taking a pitch and a number will start
jumping out at the reader for no good reason.

The goal of my efforts is:

- Helping new users to grasp the syntax,

- Helping intermediately advanced users to understand
  the differences between categories of builtins
  (typically grobs vs. contexts),

- Helping all users to discern the structure
  of examples more easily.

But not to point at editing mistakes.


[snipped]


[Jacques]
> I appreciate ‘light coloring’ of code to help locating islands in a 
> large code base, here in my doc written with… Knuth’s (La)TeX:


Again there are several uses for highlighting that
don't necessarily agree on the way to do it :-)
The more you try to be helpful for understanding
syntax by making semantic categories (grobs vs.
contexts, music functions vs. markup commands, etc.),
the more the text becomes colored. Which is proving
a problem here because LilyPond documentation examples
are so dense in different constructs that as soon
as you try to convey semantic distinctions, most of
the code becomes colored.



[Peter]
> There are various types of colour-blindness - red-green is the most 
> common. I did a quick Google on "design for colour-blind" and got 
> several useful hits, mostly for web designers. The basic message is 
> "don't rely on colour to get a message across", which isn't much help 
> to you.
>
> One way round this might be to allow the user to select colours for 
> the different distinguishable syntax elements (I think this has 
> already been suggested somewhere in this thread). And not to make it 
> too complicated. I personally get a bit fed up with Frescobaldi's 
> colours but being normally-sighted I can live with it.


By "complicated", do you mean the number of
different colors or the complexity of the
distinctions that it tries to make between
syntactical elements while staying within a
limited pool of colors? I think we are touching
a core point.

Thanks,
Jean