Re: RFC: Adding syntax highlighting to the official documentation

[Jean Abou Samra]

Le 19/12/2021 à 05:18, John Wheeler a écrit :
> Jean,
>
> My concern for color blindness stemmed from having worked on 
> government manuals probably two decades ago.  We were taught that you 
> should include nothing that relied solely on color to make sense of 
> the text.  If you are working to modern web accessibility guidelines 
> you are certainly way ahead of what I can add to the subject.  I am 
> sorry I did not pick up on that if you mentioned it before.
>
> The other concern is more a personal thing with me.  When I say 
> printed text, I was referring to pdf output. I will often print a pdf 
> file so I can better read it from paper.  When you mentioned adding 
> color to pdf files, you caught my attention.  I have seen too many 
> books that I personally have a very hard time using because either 
> someone has indiscriminately highlighted passages they thought 
> important or the book designer decided to use color in some way to 
> "guide" the reader. What other people must see as artful use of color 
> I find so distracting that I struggle to follow the text.
>
> I am showing my age here, but I have a daughter that tells me if I had 
> been born this century, I would have been tested for autistic issues.  
> Though I have never been diagnosed, I suspect she would say my 
> sensitivity to color stems from that source.
>
> I hope this helps you understand my request that some way of printing 
> black and white be preserved.
>
> Thank you,
>
> John



OK, thanks. The goal of syntax highlighting is definitely
not to introduce information in the colors, just to use
them to make the content easier to read for those who
recognize them well. And for what it's worth, the previous
discussion of the subject also showed a majority against
colorized PDF output by default. For the time being I'm only
focusing on HTML output. That has the advantage that
if even the contrast does not help, people can use
tools to adapt or remove the color scheme if they
need to. Echoing James' comment below, while not everyone
knows how to do this, I would assume someone with
some sort of vision impairment or trouble with colors
would. Right?

At any rate, I think we're definitely keeping PDF
output black-and-white by default. The open question
is whether it should be 'highlighted' in black-and-white
using bold, italics and possibly font changes,
but I am not myself proposing anything in this respect.



[Aaron]
> To add to this, color schemes in general are very personal.
>
> Thankfully, HTML documentation can leverage the power of CSS, so 
> anyone who feels strongly enough can inject a custom stylesheet to get 
> something that reads well.  However, formats like PDF where the 
> highlighting would be baked-in would not be able to adapt to 
> individual preference.  I would argue such targets should stick to 
> black and white, only using color where relevant to a snippet.
>
> As an alternative to color, perhaps the syntax highlighting could 
> focus only on varying font weight, style, etc.  This would be more in 
> keeping with, say, Knuth's approach he presented as part of literate 
> programming.  One of the things he found was that proportional fonts 
> often read better than monospace in print.  We would not have to 
> follow suit so precisely, but I'm sure there are lessons learned back 
> then that could help today.



True. But I never read PDF documentation, so
I'm a dummy with that. I leave it to others
who desire it to design and get agreement on
a scheme for PDF output (again, I can help with
the technical part, just not with the design part,
and I don't have an opinion one way or the other
on the mere principle of doing it in PDF).

Or did you mean also using black-and-white in
HTML?



[James]
> [...]
>
> Often? I'd say pretty much 'always'. Or are we talking about 'reading 
> code'?


I think there is a misunderstanding here. Proportional
vs. monospace refers to 'normal' fonts vs. typewriter
fonts. Our examples are currently in typewriter font,
namely the option apparently presented by Knuth as
worse. Highlighting with colors would not change that
(while highlighting PDFs in black-and-white could, even
if again that is not the point of this particular proposal).
However, documentation examples rely on the alignment
of columns for code formatting. I don't think font changes
with variations in width would be feasible.


> Not to single you out Aaron (so apologies), but we're losing sight of 
> the users. Developer's can do whatever they want how they want because 
> they have the knowledge and seem to 'want' this colour syntax 
> highlighting I assume because that is what they work with for their 
> day jobs. Normal users don't. They want to clean, easy to read 
> documentation without being distracted by colours.
>
> I am not on the user lists, but has anyone taken a straw poll or asked 
> anyone on that list what they think?
>
> I realise that a lot of the same people on this list lurk on the users 
> lists too but I would assume there would be many that do not.
>
> How about we produce a PDF or website with this new feature and give 
> it to the user-base for their comment?
>
> I still maintain that for our own documentation it is overkill.


A wide majority of users edit their scores in
Frescobaldi, which does syntax highlighting by
default. I have not heard anybody complain, but
then it's true that there is a ready-made button
to disable it.

So it's a good idea to poll users. If we're going to do
this, I'll wait a bit because if we hesitate on
the color scheme, it will also be an occasion to
have feedback on that.

Regards,
Jean