Le 02/01/2022 à 01:06, David Kastrup a écrit :
Jean Abou Samra<jean@abou-samra.fr> writes:
Hi all,
There is an ongoing proposal to add syntax highlighting
in LilyPond's documentation. Since it is a notable change
to the documentation reading experience, user feedback would
be appreciated. You can browse a syntax-highlighted version
of the notation manual here:
http://abou-samra.fr/highlighting-demo/notation/index.html
For comparison, this is the current notation manual:
https://lilypond.org/doc/v2.23/Documentation/notation/index.html
The main questions are: what do you think of the principle?
And is the color scheme good enough?
I just followed the discussion without much attention because I did not
think that it would affect me whether or not there was syntax
highlighting. That probably was a mistake. Taking a random example:
There is a wild mixture of colors and font styles without apparent rhyme
or reason. I don't see that it helps legibility or conveys any useful
categories. I cannot even figure out what it thinks it is doing.
\layout, \context, \remove are reserved words in the syntax and are
printed in boldface and black. So is \override which is printed in
normalface blue, like \relative and \repeat. But \relative is a music
function while \repeat is a reserved word. Beam.breakable is printed in
red while unfold is printed in blue.
While you and me have the perspective of parser
keywords vs. music functions, I think we can agree
that this is mostly irrelevant to highlighting.
A typical user does not need or want to care
whether \repeat is implemented as a token or a
music function, and probably does not know the
difference anyway (until they try to redefine it,
in which case the lexer gives them a friendly warning).
What is relevant is clearly the function in input.
From this perspective, the highlighting applies one
rule of thumb: what yields an articulation is purple,
everything else that yields music is blue. From this
point of view, the example you show is consistent.
The case of \override in a context definition is
somewhat special since it bypasses music, but it
would be awkward to have it in a different color than
\override in the flow of music, particularly since
something like \once \override in a context definition
works via music (and we briefly discussed making
\override work the same some months ago).
However, because all rules are there to be broken,
there are notable exceptions to the "what yields
music is blue" rule, such as \new. There are two reasons
to this. One is that \new pairs with \context in music,
but \context should really be a keyword in output
definitions, and the lexer does not (yet) try to
distinguish between these cases. The other reason is
that \new drives the structure of many examples
and highlighting it in bold seemed to help grasping
good enough a number of them to be worth an exception.
So this is basically an admittedly handwaving reasoning
of "you want to see this first because it is an
important structuring element". Other important
such exceptions are mode switchers such as \addlyrics
and friends. Now, Valentin proposes a scheme where
(most?) music functions are bold too, so this could
be reconsidered.
unfold is blue because it's considered part of
the essence of the "\repeat something" command. It
don't pretend that is the best choice, and since I
eventually decided not to highlight clef names in
blue I should likely revert it.
Beam.breakable is red like all grob property paths.
There is apparently a large collection of colors
To be exact, five colors in total if you count
grey. That's not exactly what I would call a
large collection ...
and some font styles
Just bold for keywords. Nothing more.
[snipped]
[Valentin]
Hello Jean, hello David,
I do like the idea, but I do agree with David to some extent. Syntax
highlighting should emphasize the structure of the file and thus make
reading
easier. But if it gets too colorful in terms of contrast of colors
the colors
simply distract you.
For example there is no good reason for coloring all numbers some
outstanding
way. Frescobaldi does this, but that just creates distracting dots of
color in
the code. And numbers tend to be quite discernible, so you do not
really need
a special color to mark them.
It seemed to help discerning articulations such as [(
from dotted durations and also those with multipliers.
Not that it matters so much to me though. Or perhaps
I should use a less bright color?
That being said your color scheme is much better than Frescobaldi’s
scheme,
which is appallingly distracting. See the appended file for a
comparison of
Frescobaldi and KDE Kate (which is by no means perfect, but at least an
improvement...).
I think your color scheme could be improved easily by doing something
like in
the other screenshot (taking the same snippet as David).
Ok, thanks for trying out, but could you explain what
it does more precisely? Specifically, what is setting
apart \tuplet so that it is not bold? Also, you seem
no longer to highlight grob properties, does that mean
context properties are not highlighted as well?
(https://lists.gnu.org/archive/html/lilypond-devel/2021-12/msg00107.html
gives a script you can use to play around and make specific
proposals.)
[Calvin]
Would it be possible to have a menu for changing the highlighting
settings to create some customizability? I'm not familiar with web
development at all so I don't know if this would be difficult to
implement.
That's conceivable, but quite a bit of work for unlikely
widespread usage, and also requires JavaScript and cookies
which is usually not very appreciated in the free software
world around GNU LilyPond. Luckily, there is no need for
it to be implemented in LilyPond. The default CSS stylesheet
is at
http://abou-samra.fr/highlighting-demo/css/lilypond-highlighting.css
(of course this will/would be on the lilypond.org server
eventually). Using your browser, possibly with an extension,
you can inject custom CSS, applying any styling you want.
For example, with Firefox, you can use Stylus:
https://addons.mozilla.org/fr/firefox/addon/styl-us/
Jean