PDF readability: the colour palette results in too low contrast for highlighted code

[erlend-aasland]

Created from #110383.

Regarding the PDF readability issue:

[...] I appreciate the wealth of information in the Python documentation but have encountered challenges with the PDF format. Specifically, the code sample readability is hindered, making it hard to highlight and annotate effectively. Please have a look at the picture attached , you will find the code sample hard to read.

To enhance accessibility, I suggest optimizing code sample color contrast.
This improvement would benefit users across preferences and ensure a more
user-friendly experience.

The image attached to that report, is attached here:

I downloaded the docs as PDF, and currently they're rendered like this:

IMO, there is an improvement, but I'm not sure if it's a good enough improvement. Comments?

[erlend-aasland]

Hugo commented #110383 (comment):

The 4.43:1 contrast ratio of green digits on grey is much better than before, but doesn't quite meet the WCAG AA guidelines of 4.5:1.

https://webaim.org/resources/contrastchecker/?fcolor=247F51&bcolor=F2F2F2

The grey symbols (5.12:1) meets AA and the black text (18.75:1) meets both AA and AAA (7:1).

I'm not sure where these colours are defined.

I responded #110383 (comment):

Me neither, but ISTM the PDFs are generated from make -C Doc dist. I'm suspecting it might be the Sphinx LaTeX package sphinx.sty.

[erlend-aasland]

This may be a Sphinx issue, cc. @AA-Turner.

[erlend-aasland]

See also (cc. @picnixz, who's been recently active in our repo):

• LaTeX: background gray in PDF code-blocks has a lesser contrast for xelatex with non-highlighted tokens  sphinx-doc/sphinx#11269

[picnixz]

The problem we had was mostly because of the font families and an extensible glyph support. More precisely, we need¹:

a monospace Unicode font supporting:

• at least Latin Greek and Cyrillic (CJK goes via separate pathways a priori but it would be a plus to have simplified Chinese)
• Unicode code points involved in output of Linux tree command

Ideally:

• does not require texlive-fonts-extra for Ubuntu and if it does was already included there with 18.04LTS, is also available via TeXLive,
• has been tested with fontspec \setmonofont with Path and no extension specified so that it will work whether font is opentype or TrueType and whether it is system font or in LaTeX installation font tree both with xelatex and lualatex

And it has to look good on gray background.

We can disregard the last 'gray background' condition under the assumption that someone finds a good background for code blocks. It should be possible to configure the exact color used for listings in some latex_preamble or so but I don't remember exactly how.

Footnotes

1. https://github.com/sphinx-doc/sphinx/issues/11269#issuecomment-1513587356 ↩