move r[rules] to the left of the main body, using a grid #1710

WaffleLapkin · 2025-01-08T17:42:42Z

See discussion in zulip: https://rust-lang.zulipchat.com/#narrow/channel/399173-t-spec/topic/Rule.20readability.20in.20the.20reference/near/492412172

This requires some quite awkward CSS changes, but it does work and does look a lot better...

i.e. this replaces ```markdown # UwU r[uwu] ``` with ```markdown r[uwu] # UwU ``` This is required because the new grid system assumes that a rule is related to the *following* element. But also, it makes it clear in the source which element the rule is related to, as it's curently ambiguous. Also (2), existing annotations are not 100% consistent. I've done this using the following two irregular "regex" replacements: 1. `([^\]]\n|^(?<!\n))(^#+ [^\n]+)\n\n?(r\[.+\])\n*(r\[)` ==>> `$1$3\n$2\n\n$4` (~255 cases) 2. `([^\]]\n|^(?<!\n))(^#+ [^\n]+)\n\n?(r\[.+\])\n+` ==>> `$1$3\n$2\n\n` (~99 cases) With the latter one being reviewed manually, since it can produce bad replacements in cases like this, where the rule relates to the following paragraph/element, rather than the preceding heading: ```markdown # OwO r[meow] >////< mEeoowW prRRrr purrrrrrRr :3 mrrrrrreww meEooww purrrrrr~ Mrrrew ```

i.e. they'll show their id on hover; good for when they are wrapped or hidden.

ehuss

Thanks, I appreciate your help with this!

I pushed an update to support h5 and h6 headers. I think I got it right, though I'm not sure. It at least looks ok.

I'm a little concerned about the complexity of the CSS here, but it seems to work pretty well. (I get jittery with any CSS beyond the most basics...)

Adjusts the position of rules with headers to match the style from rust-lang#1710

WaffleLapkin · 2025-01-15T22:13:31Z

h5/h6 support looks good to me.

I'm a little concerned about the complexity of the CSS here, but it seems to work pretty well. (I get jittery with any CSS beyond the most basics...)

Yea, I'm not very happy with the complexity either. But I don't really see easier ways to achieve the same. (things would be much easier if we didn't try to display rule names though)

I think I've also checked and all the CSS features this PR is using are supported in >92% of users' browsers globally (and likely even more in tech savy people who would read the reference, but idk). So... it's not that bad ig.

Update books ## rust-lang/book 3 commits in 82a4a49789bc96db1a1b2a210b4c5ed7c9ef0c0d..fa312a343fbff01bc6cef393e326817f70719813 2025-01-22 17:14:29 UTC to 2025-01-22 15:09:26 UTC - chore: reformat src with dprint (rust-lang/book#4211) - Redirects: get rid of the weird gap in Ch. 20 sections! (rust-lang/book#4209) - Document that `use` is also for `precise capturing` (rust-lang/book#4210) ## rust-lang/edition-guide 1 commits in d56e0f3a0656b7702ca466d4b191e16c28262b82..4ed5a1a4a2a7ecc2e529a5baaef04f7bc7917eda 2025-01-21 21:39:56 UTC to 2025-01-21 21:39:56 UTC - Add alternatives for static-mut-refs (rust-lang/edition-guide#354) ## rust-lang/nomicon 3 commits in 625b200e5b33a5af35589db0bc454203a3d46d20..bc2298865544695c63454fc1f9f98a3dc22e9948 2025-01-23 19:01:24 UTC to 2025-01-20 14:37:52 UTC - corrected grammatical error. (rust-lang/nomicon#477) - Remove `#![start]` attribute (rust-lang/nomicon#478) - Update guidance on uninitialized fields to use &raw mut instead of addr_of_mut! (rust-lang/nomicon#476) ## rust-lang/reference 10 commits in 293af991003772bdccf2d6b980182d84dd055942..93b921c7d3213d38d920f7f905a3bec093d2217d 2025-01-25 21:59:01 UTC to 2025-01-14 17:28:04 UTC - distinct 'static' items never overlap (rust-lang/reference#1657) - Change `'_static` to `'static` as an invalid lifetime parameter name (rust-lang/reference#1721) - reword reference about inert attributes (rust-lang/reference#1719) - Provide a better error message for broken links in mdbook-spec (rust-lang/reference#1716) - Remove unstable vectorcall (rust-lang/reference#1717) - Move the function pointer example (rust-lang/reference#1718) - references and Box must be non-null (rust-lang/reference#1715) - Fix filename for theme customization (rust-lang/reference#1711) - Add Identifier Syntax to Several Chapters (rust-lang/reference#1597) - move r[rules] to the left of the main body, using a grid (rust-lang/reference#1710)

Rollup merge of rust-lang#136143 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 3 commits in 82a4a49789bc96db1a1b2a210b4c5ed7c9ef0c0d..fa312a343fbff01bc6cef393e326817f70719813 2025-01-22 17:14:29 UTC to 2025-01-22 15:09:26 UTC - chore: reformat src with dprint (rust-lang/book#4211) - Redirects: get rid of the weird gap in Ch. 20 sections! (rust-lang/book#4209) - Document that `use` is also for `precise capturing` (rust-lang/book#4210) ## rust-lang/edition-guide 1 commits in d56e0f3a0656b7702ca466d4b191e16c28262b82..4ed5a1a4a2a7ecc2e529a5baaef04f7bc7917eda 2025-01-21 21:39:56 UTC to 2025-01-21 21:39:56 UTC - Add alternatives for static-mut-refs (rust-lang/edition-guide#354) ## rust-lang/nomicon 3 commits in 625b200e5b33a5af35589db0bc454203a3d46d20..bc2298865544695c63454fc1f9f98a3dc22e9948 2025-01-23 19:01:24 UTC to 2025-01-20 14:37:52 UTC - corrected grammatical error. (rust-lang/nomicon#477) - Remove `#![start]` attribute (rust-lang/nomicon#478) - Update guidance on uninitialized fields to use &raw mut instead of addr_of_mut! (rust-lang/nomicon#476) ## rust-lang/reference 10 commits in 293af991003772bdccf2d6b980182d84dd055942..93b921c7d3213d38d920f7f905a3bec093d2217d 2025-01-25 21:59:01 UTC to 2025-01-14 17:28:04 UTC - distinct 'static' items never overlap (rust-lang/reference#1657) - Change `'_static` to `'static` as an invalid lifetime parameter name (rust-lang/reference#1721) - reword reference about inert attributes (rust-lang/reference#1719) - Provide a better error message for broken links in mdbook-spec (rust-lang/reference#1716) - Remove unstable vectorcall (rust-lang/reference#1717) - Move the function pointer example (rust-lang/reference#1718) - references and Box must be non-null (rust-lang/reference#1715) - Fix filename for theme customization (rust-lang/reference#1711) - Add Identifier Syntax to Several Chapters (rust-lang/reference#1597) - move r[rules] to the left of the main body, using a grid (rust-lang/reference#1710)

Update books ## rust-lang/book 3 commits in 82a4a49789bc96db1a1b2a210b4c5ed7c9ef0c0d..fa312a343fbff01bc6cef393e326817f70719813 2025-01-22 17:14:29 UTC to 2025-01-22 15:09:26 UTC - chore: reformat src with dprint (rust-lang/book#4211) - Redirects: get rid of the weird gap in Ch. 20 sections! (rust-lang/book#4209) - Document that `use` is also for `precise capturing` (rust-lang/book#4210) ## rust-lang/edition-guide 1 commits in d56e0f3a0656b7702ca466d4b191e16c28262b82..4ed5a1a4a2a7ecc2e529a5baaef04f7bc7917eda 2025-01-21 21:39:56 UTC to 2025-01-21 21:39:56 UTC - Add alternatives for static-mut-refs (rust-lang/edition-guide#354) ## rust-lang/nomicon 3 commits in 625b200e5b33a5af35589db0bc454203a3d46d20..bc2298865544695c63454fc1f9f98a3dc22e9948 2025-01-23 19:01:24 UTC to 2025-01-20 14:37:52 UTC - corrected grammatical error. (rust-lang/nomicon#477) - Remove `#![start]` attribute (rust-lang/nomicon#478) - Update guidance on uninitialized fields to use &raw mut instead of addr_of_mut! (rust-lang/nomicon#476) ## rust-lang/reference 10 commits in 293af991003772bdccf2d6b980182d84dd055942..93b921c7d3213d38d920f7f905a3bec093d2217d 2025-01-25 21:59:01 UTC to 2025-01-14 17:28:04 UTC - distinct 'static' items never overlap (rust-lang/reference#1657) - Change `'_static` to `'static` as an invalid lifetime parameter name (rust-lang/reference#1721) - reword reference about inert attributes (rust-lang/reference#1719) - Provide a better error message for broken links in mdbook-spec (rust-lang/reference#1716) - Remove unstable vectorcall (rust-lang/reference#1717) - Move the function pointer example (rust-lang/reference#1718) - references and Box must be non-null (rust-lang/reference#1715) - Fix filename for theme customization (rust-lang/reference#1711) - Add Identifier Syntax to Several Chapters (rust-lang/reference#1597) - move r[rules] to the left of the main body, using a grid (rust-lang/reference#1710)

ehuss · 2025-02-20T16:42:54Z

@WaffleLapkin This seems to have broken the rendering for the tests links. Is that something you can look at fixing?
See https://doc.rust-lang.org/1.84.0/reference/input-format.html#r-input.shebang.inner-attribute for how this used to work.

If you look at https://doc.rust-lang.org/nightly/reference/input-format.html on a narrow screen, it does weird wrapping (or even on a wide screen, it looks a little weird). The chevrons also seem to appear twice, and the links are underneath the left page navigation. The popup is also in the wrong location.

I'm wondering if maybe when it is in wide mode, it could link underneath the rule name? Maybe something like:

And then have the popup show towards the right?

I'm not sure what to do in narrow mode. I can't think of a good way to link it. Do you have any ideas?

As a side note, in narrow mode, the [*] cuts off the leftmost [, and ends up look a little weird.

I'm wondering if there is a way to prevent that? I don't really understand how the layout works here.

WaffleLapkin · 2025-02-22T19:46:57Z

@ehuss will look into this next week.

WaffleLapkin added 9 commits January 8, 2025 18:05

move r[rules] to the left of the main body, using a grid

7575dc3

fixup margins

0cccb2a

try to fixup footnote definitioon margins

bc02bf9

align rules to the elements after them

d5cdf55

word-wrap rule links

5f19268

hide rules behind [*], if the "margin" is too thin

ce4c198

title rule links

1f9ea21

i.e. they'll show their id on hover; good for when they are wrapped or hidden.

Move rule links in the presence of » b/c of linked headers

13869f4

rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Jan 8, 2025

Add h5/h6 support

1f12877

ehuss approved these changes Jan 14, 2025

View reviewed changes

ehuss enabled auto-merge January 14, 2025 17:27

ehuss added this pull request to the merge queue Jan 14, 2025

Merged via the queue into rust-lang:master with commit f80986b Jan 14, 2025
5 checks passed

ehuss added a commit to chorman0773/rust-lang-reference that referenced this pull request Jan 14, 2025

Adjust position of rules attached to headers

415cafe

Adjusts the position of rules with headers to match the style from rust-lang#1710

WaffleLapkin deleted the pretty-rule-refs branch January 15, 2025 22:11

rustbot mentioned this pull request Jan 27, 2025

Update books rust-lang/rust#136143

Merged

WaffleLapkin mentioned this pull request Feb 7, 2025

fixup » insertion for rules #1730

Merged

WaffleLapkin mentioned this pull request Feb 24, 2025

fixup test links #1741

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

move r[rules] to the left of the main body, using a grid #1710

move r[rules] to the left of the main body, using a grid #1710

WaffleLapkin commented Jan 8, 2025

ehuss left a comment

WaffleLapkin commented Jan 15, 2025 •

edited

Loading

ehuss commented Feb 20, 2025

WaffleLapkin commented Feb 22, 2025

move r[rules] to the left of the main body, using a grid #1710

move r[rules] to the left of the main body, using a grid #1710

Conversation

WaffleLapkin commented Jan 8, 2025

ehuss left a comment

Choose a reason for hiding this comment

WaffleLapkin commented Jan 15, 2025 • edited Loading

ehuss commented Feb 20, 2025

WaffleLapkin commented Feb 22, 2025

WaffleLapkin commented Jan 15, 2025 •

edited

Loading