Fix font size for [src] links in headers

[GuillaumeGomez]

Fixes #90384.

cc @jsha
r? @camelid

[rust-highfive]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

[camelid]

Sorry, I don't have enough familiarity with the CSS to review. r? @jsha

[jsha]

Thanks for fixing this! This is also mentioned in some of the readability / accessibility threads around styling - that the [src] link is slightly bigger than the heading, for instance in method headings.

I think the actual fix is not quite right - it's providing overrides on top of overrides on top of overrides. What we want is to set the font size at the correct level and then avoid overriding it. Also, our heading sizes are 1em, 1.1em, 1.15em, 1.3em, 1.4em, 1.5em. 1.1em corresponds to 17.6px, so setting srclink to 17px is still not quite exactly right.

One of the problems here: Typically we'd like to set the font size on the h3 and indeed we do. But the h3 and the srclink are siblings, rather than srclink being a child of h3.

That means we should set the font size on the parent element. So for instance the outer div here:

<div id="associatedconstant.MAX" class="associatedconstant has-srclink">
  <div class="rightside"><span class="since" title="Stable since Rust version 1.43.0">1.43.0</span>
    <a class="srclink" href="../src/core/num/f32.rs.html#404" title="goto source code">[src]</a>
  </div>
  <a href="#associatedconstant.MAX" class="anchor"></a>
  <h4 class="code-header">pub const <a href="#associatedconstant.MAX" class="constant">MAX</a>:
     <a class="primitive" href="primitive.f32.html">f32</a>
   </h4>
</div>

And the outer div here:

<div id="impl-1" class="impl has-srclink">
  <div class="rightside">
    <a class="srclink" href="../src/core/num/f32.rs.html#375-1119" title="goto source code">[src]</a>
  </div>
  <a href="#impl-1" class="anchor"></a>
  <h3 class="code-header in-band">impl <a class="primitive" href="primitive.f32.html">f32</a></h3>
</div>

Then we can remove the overrides of font-size for h3.code-header and h4.code-header:

h3.code-header {
    font-size: 1.1em;
}

h4.code-header {
    font-size: 1em;
}

Replacing them with (I think) font-size: inherit so they get the font-size of their div parent rather than the global h3 / h4 font size.

Alternately, maybe we shouldn't set a "global" h3 / h4 font size, but should have a set of font sizes for prose headings, and a separate set of font sizes for code headers, so they don't conflict.

[jsha]

Also part of the problem is that the rule we use to make the target highlight is:

:target, :target > * {
	background-color: #494a3d;
}

That :target > * means all immediate descendents of the target element will have their background color set independently, which can result in this sort of "bumping out".

We need to reduce this selector to just :target. Otherwise even after we make the font-size the same between the code header and the srclink, we'll still see a very slight bump-out because they use different typefaces, and the cap height of those typefaces differs.

[jsha]

our heading sizes are 1em, 1.1em, 1.15em, 1.3em, 1.4em, 1.5em. 1.1em corresponds to 17.6px, so setting srclink to 17px is still not quite exactly right.

Doing some experimentation, I realized our current approach of setting font-size in terms of em is probably a bad fit, because if we apply such a rule multiple times we will get compounding results. This is explained here: https://developer.mozilla.org/en-US/docs/Web/CSS/font-size#ems

One important fact to keep in mind: em values compound. Take the following HTML and CSS:

html {
  font-size: 62.5%; /* font-size 1em = 10px on default browser settings */
}
span {
  font-size: 1.6em;
}

<div>
<span>Outer <span>inner</span> outer</span>
</div>

The result is: ["outer" is small and "inner" is big]

So I think we should actually switch to pixel-based font sizes to avoid accidental compounding.

Edit: actually "rem" fixes this problem: "rem values were invented in order to sidestep the compounding problem. rem values are relative to the root html element, not the parent element." And defining font sizes in px is not accessible. So I think we should use rem.

I'm working on a counterproposal branch, which I'll have up in a sec.

[jsha]

Here's my counterproposal branch: https://github.com/rust-lang/rust/compare/master...jsha:heading-sizes?expand=1. Instead of adding more overrides, I removed some of the already-existing overrides, and made the overall heading rules more specific.

The idea here is that we would have specific font-size rules for different headings in difference situations. I think the rules I've set up cover all situations, but to be sure I added (temporarily) default rules for h2-h3 that set a very large font-size. If you spot any inappropriately large headings when browsing around the demo, that's a bug I need to fix. If we go this route I would remove those too-large rules before merge.

I also switched the font-size specifications for the rules I touches so they're in rem. There are some remaining font-size specifications elsewhere in px, em, and %. We should follow up in a separate PR to change those all to rem.

Demos at:

https://rustdoc.crud.net/jsha/heading-sizes/std/string/struct.String.html
https://rustdoc.crud.net/jsha/heading-sizes/std/vec/struct.Vec.html
https://rustdoc.crud.net/jsha/heading-sizes/std/io/trait.Read.html
https://rustdoc.crud.net/jsha/heading-sizes/std/iter/trait.Iterator.html

[GuillaumeGomez]

@jsha Your proposal looks great but is incomplete:

The background should be on all content like this:

But otherwise, I think it's a better take. Do you mind if I cherry-pick your commit and modify it?

[jsha]

Please go ahead!

…

On Thu, Dec 30, 2021, 07:18 Guillaume Gomez ***@***.***> wrote: @jsha <https://github.com/jsha> Your proposal looks great but is incomplete: [image: Screenshot from 2021-12-30 13-15-46] <https://user-images.githubusercontent.com/3050060/147751292-56449d63-9b49-4231-8fc2-7f2394b8a8fd.png> The background should be on all content like this: [image: Screenshot from 2021-12-30 13-17-04] <https://user-images.githubusercontent.com/3050060/147751308-4ae0c46e-b2c6-477c-81e9-f05613b17fb3.png> But otherwise, I think it's a better take. Do you mind if I cherry-pick your commit and modify it? — Reply to this email directly, view it on GitHub <#92404 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABVYLMDOJ2WLOUK5GWQURDUTREZJANCNFSM5K577NRQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[bors]

☔ The latest upstream changes (presumably #92580) made this pull request unmergeable. Please resolve the merge conflicts.

[GuillaumeGomez]

@jsha It would be actually more complicated to do what you suggested from what I tried: it requires a lot more of code to achieve the same result. :-/

[jsha]

Which part? Fixing the target selector, or fixing the heading selectors?

I'm okay not making the suggested fixes to heading selectors, but I think the fix to the target selector is needed if you want this to be reliably correct.

[GuillaumeGomez]

I was talking about the heading selectors. I will send the target selector change in a few seconds. ;)

[GuillaumeGomez]

Done!

[jsha]

@bors r+ rollup

[bors]

📌 Commit 3b70c6e has been approved by jsha