Re: RFC: Adding syntax highlighting to the official documentation

[Jean Abou Samra]

[Me]
> Hi Mats,
>
> Thanks for your thoughts!
>
>
> Le 31/01/2022 à 09:19, Mats Bengtsson a écrit :
> >     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.
>
>
> Will do.



Whoops, I spoke too fast, sorry. To meaningfully
demonstrate highlighting without focusing the
reader's attention on the wrong thing, I need the
capability to highlight code without also showing
the output image. So this will have to wait on
the second improvement that you suggested.



[Werner]
> This is an excellent suggestion!
>
> > So that is doable, but as you can see there is a fair bit of work to
> > invest, especially for changing many instances of @example to
> > @lilypond[verbatimonly,quote] ...
> >
> > $ git grep "@example" | wc -l
> > 4626
> I think this is not an issue.  There is no need to update all
> instances immediately – `@example` will work in the future, too, so
> the work can be done incrementally.


True. Part of it can also be alleviated via scripting;
updating only the examples in the English documentation is
less work, and they are mostly the same in translations.
OK, putting on my list, but I still plan to do the
Scheme lexer improvements before that (and it definitely
deserves a separate merge request anyway). If you
want to have a go in the mean time, feel free :-)

Best,
Jean