[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: RFC: Adding syntax highlighting to the official documentation

From: Jean Abou Samra
Subject: Re: RFC: Adding syntax highlighting to the official documentation
Date: Mon, 31 Jan 2022 18:02:44 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.5.0

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.

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
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 :-)


reply via email to

[Prev in Thread] Current Thread [Next in Thread]