rustdoc: #13771: Make html links inside paragraphs more readable

[ipetkov]

All links inside docblocks will have their color set to #4e8bca (a light blue color to contrast against the black text). This color also offers a visible contrast from the surrounding text if viewed as grayscale, making it suitable for accessability.

Docblock links will also be underlined when hovered over.

Before:

After (links underlined only on hover, cursor not shown in image):

Fix #13771

[adrientetar]

Can you underline only on hover?

[ipetkov]

Sure!

Updated and rebased

[lifthrasiir]

@adrientetar Uh, then we would have only the color to distinguish links and it is bad for accessibility. I think we need underlines at least in the docblock area.

[ipetkov]

@lifthrasiir what about bolding links like the previous docs did? If so, should another color be used or would that be enough?

[adrientetar]

@lifthrasiir Do you have something concrete backing this? MSDN shows that color-recognition deficiencies still let the people see blue.
So which kind of deficiencies are we talking about? I had an economics teacher that had major vision problems and he would require us to write in black and had a special kind of magnifying glass with white lighting. I assume people with major vision deficiencies use a screen reader, otherwise a CSS injection plugin will override styles conveniently (e.g., Stylish for Firefox).

I don't see any concrete evidence of cases where someone would a/ not see the blue color and b/ not have any software alternative available that would not require a mandatory edit to the mainline stylesheet – otherwise they would not be able to browse most modern websites (GitHub here included) (?). Bootstrap does not underline links and has a committance towards accessibility, the accessibility plugin itself does not add mandatory underline either...

Underlining is being phased out is modern websites because it halts the document flow, much more than a color change does.
If there was a case of both a/ and b/ above being fulfilled then sure I would be backing always-on underlining, but there does not seem to be one afaict.

[lifthrasiir]

@adrientetar Right, using the color and nothing else itself is not a problem. It is a problem that using the color which doesn't have enough contrast from the surrounding text. (And there are certainly people who cannot distinguish hues at all.) My initial comment is based on the fact that @ipetkov's screenshot doesn't seem to have enough contrast when grayscaled.

Some concrete numbers: WCAG 2.0 Level AA requires at least 3:1 contrast for most visual cues (it's actually 4.5:1 except for large texts, but for the purpose of this discussion let's think it as an absolute minimum). The PR uses #333333 for text and #4d76ae for link, yielding the contrast ratio of 2.72:1 (you can verify it with a checker). For comparison Bootstrap seems to use #333333 for text and #4e8bca for link, yielding the ratio of 3.53:1. Of course this greatly depends on the actual color space and gamma, and color-blind users would certainly use a high-contrast configuration.

Well, this seems to suggest that one can meet the basic accessibility by simply making the link color slightly lighter. What do you think about this?

Note: We should also eventually think about other visual cues for the accessibility.

[adrientetar]

Yup no problem about making it lighter.

[ipetkov]

Bootstrap's #4e8bca color for links definitely offers better contrast on a grayscale, and it is aesthetically similar to the current one.

@lifthrasiir and @adrientetar do you think this is acceptable?

#4e8bca for link color:

Grayscale:

[adrientetar]

It's fine by me.

[lifthrasiir]

Yeah, it looks definitely better.

[ipetkov]

Should links be underlined on hover?

The old doc style did not do this, but GitHub for example does show underlines on hover.

[adrientetar]

Standalone documentation does it but it's mostly a leftover from Bootstrap. Do not have a strong bias with this.

[ipetkov]

Updated once more