Re: RFC: Adding syntax highlighting to the official documentation

[James]

On 19/12/2021 06:46, Aaron Hill wrote:
> On 2021-12-18 8:18 pm, John Wheeler wrote:
> > 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. [ . . . ]
>
> 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.

Anyone?

I couldn't. I wouldn't even know where to start.

How about

"Programmers or developers who feels strongly enough can inject a custom 
stylesheet to get something that reads well for them, and the rest of us 
mere mortals just get on with our lives without this?

> 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. 

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

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.

James

--
Regards

James