[rustdoc] Feature Request: Allow code wrapping #127334
Comments
|
Hi, thank you for the idea. About which code views are you talking? can you provide example URLs? I'm asking because there are actually two separate ones:
|
Like it says |
|
Ah, that's even option 3), not the code views for the crate itself, but code blocks in the docs. I'm not sure if this is a rustdoc issue (where we don't have the "run" button yet), or an issue for the stdlib docs. |
|
Sorry I still don't understand what's being asked. ^^' |
Are you talking to me or...? I mean wrapping the code blocks on the rust docs website. As in not having any overflow-x..? Having the text wrap to the next line, so you don't need to scroll left and right, to read the code block |
|
Oh I see. So a change in rustdoc. Moving the issue to the right repository. |
rustbot
added
the
needs-triage
GuillaumeGomez
changed the title
GuillaumeGomez
added
T-rustdoc
|
In case it's not clear for everyone, let me expand a bit (please correct me if I'm wrong @aramrw): Currently, the code examples in Rust HTML documentation are scrollable if they are too wide. The idea here would be to add a setting allowing for the code examples to instead wrap to the next line. Now for the implementation: we need to be careful how this new setting would interact with the line numbers on the left (if the setting is enabled). One thing I'm not clear about: @aramrw, would you want this setting to be applied to both code examples and source code pages or only to code examples? I think it's fine to add such a setting. If @rust-lang/rustdoc-frontend agrees, I'll add it. |
If it's possible to add it for both the code examples & the source code it would be much appreciated 👍🏼 |
|
It's fine. Correct line numbers with soft wrapping is essentially a CSS table, which means the DOM needs redone. It's not just a one-line change, but it is feasible, and I'd approve it. It makes sense that you'd want it. |
|
A table has a limit of 10.000 rows, so might be problematic on source code page with some very big files. |
If that's the case then only wrapping code blocks is fine because (on iphone at least), the source code allows you to pinch in and out very easily to see all the text, or at least most of it. However the code block examples don't have that, so to see all the text you need to go into the browsers menu and keep messing with the zoom in & out buttons. |
Is that spelled out anywhere? I wrote a cursory test for this, and it seems to work fine in Firefox and Safari (I haven't tried it in Chrome). <!DOCTYPE html>
<script>
document.write("<table>");
for (i = 0; i < 10000; ++i) {
document.write("<tr><th>" + i + "</th><td>Nam provident a nihil omnis iure nihil. Ipsum enim omnis rerum dolorum quibusdam ab dolore quis. Vitae consequatur id ipsam ipsum mollitia eaque. Maxime et officia temporibus debitis consequuntur doloremque.</td></tr>");
}
document.write("<tr><th>This test row is added to ensure things look reasonable with very long columns</th><td>Nam provident a nihil omnis iure nihil. Ipsum enim omnis rerum dolorum quibusdam ab dolore quis. Vitae consequatur id ipsam ipsum mollitia eaque. Maxime et officia temporibus debitis consequuntur doloremque.</td></tr>");
</script>The closest thing I'm able to find is a bug related to grids being limited to 10,000 lines, but I can't find anything on tables being limited. |
|
#88545
Looks like it was grid layout and 1000 items, maybe?
|
|
One idea: instead of having an option for this, maybe just make wrapping the default on mobile devices (i.e., screens that are sufficiently narrow by some heuristic). I'm wary of requiring too much configuration of rustdoc. |
I was looking for this discussion, thanks so much! So it was not for tables but for grids, good to know! One less problem to worry about.
We enter in the tricky area of personal taste. It's a case where being able to ask all rust doc users would be super useful. |
|
I've been meaning to come here and post exactly what @camelid said. Our default position should be to not introduce new settings but try to just do the best thing. If we put it behind a setting, very few people will actually know about it and use it, but we will still bear the full burden of maintaining both versions. In this case, the right thing is clearly to line-wrap on all platforms (not just mobile). Horizontal scrolling is a terrible experience on desktop / wide screens too. This page has an example of doing line numbers with wrapping. It uses CSS counters, and seems pretty tidy. |
|
It can work for code examples, but not for source code as we need them to be link. But noted for the horizontal scrolling. Will make our work simpler. |
|
Another issue I didn't think of is that we use style with CSS classes across lines (so if you have a multi-line comment, it's currently only one element). It would greatly increase the size of the DOM. This feature is definitely more tricky than I initially thought... |
|
any updates...? |
|
Yep, found an acceptable middle-ground for this feature to be done in #136829. It's just the first step but adding this setting should be pretty easy/quick from there. |
…nto-code, r=notriddle [rustdoc] Move line numbers into the `<code>` directly Fixes rust-lang#84242. This is the first for adding support for rust-lang#127334 and also for another feature I'm working on. A side-effect of this change is that it also fixes source code pages display in lynx since they're not directly in the source code. To allow having code wrapping, the grid approach doesn't work as the line numbers are in their own container, so we need to move them into the code. Now with this, it becomes much simpler to do what we want (with CSS mostly). One downside: the highlighting became more complex and slow as we need to generate some extra HTML tags directly into the highlighting process. However that also allows to not have a huge HTML size increase. You can test the result [here](https://rustdoc.crud.net/imperio/move-line-numbers-into-code/scrape_examples/fn.test_many.html) and [here](https://rustdoc.crud.net/imperio/move-line-numbers-into-code/src/scrape_examples/lib.rs.html#10). The appearance should have close to no changes. r? ``@notriddle``
Rollup merge of rust-lang#136829 - GuillaumeGomez:move-line-numbers-into-code, r=notriddle [rustdoc] Move line numbers into the `<code>` directly Fixes rust-lang#84242. This is the first for adding support for rust-lang#127334 and also for another feature I'm working on. A side-effect of this change is that it also fixes source code pages display in lynx since they're not directly in the source code. To allow having code wrapping, the grid approach doesn't work as the line numbers are in their own container, so we need to move them into the code. Now with this, it becomes much simpler to do what we want (with CSS mostly). One downside: the highlighting became more complex and slow as we need to generate some extra HTML tags directly into the highlighting process. However that also allows to not have a huge HTML size increase. You can test the result [here](https://rustdoc.crud.net/imperio/move-line-numbers-into-code/scrape_examples/fn.test_many.html) and [here](https://rustdoc.crud.net/imperio/move-line-numbers-into-code/src/scrape_examples/lib.rs.html#10). The appearance should have close to no changes. r? ``@notriddle``
|
Opened PR to add the feature in #136991. |
…triddle [rustdoc] Add new setting to wrap source code lines when too long Fixes rust-lang#127334. Wrapped lines look like this:  It works in both source code pages and doc pages. You can test it [here](https://rustdoc.crud.net/imperio/code-wrapping/bar/index.html). r? `@notriddle`
Rollup merge of rust-lang#136991 - GuillaumeGomez:code-wrapping, r=notriddle [rustdoc] Add new setting to wrap source code lines when too long Fixes rust-lang#127334. Wrapped lines look like this:  It works in both source code pages and doc pages. You can test it [here](https://rustdoc.crud.net/imperio/code-wrapping/bar/index.html). r? ``@notriddle``
Would be nice to have a setting (or just a button) that could have the code wrap, gets tiring if you are reading lots of code on your phone to scroll back and forth.
My bad if this has been requested before, I didn't see it in any issues yet
The text was updated successfully, but these errors were encountered: