rust-cookbook
rust-cookbook copied to clipboard
rust-lang-nursery
Problem with discovery of Hidden Lines (error-chain boilerplate)
All the examples hide the error_chain functionality behind the hidden lines feature.
I stumbled upon this myself when I first tried the cookbook, and someone on reddit also did.
It should be simple to write a piece of javascript that alerts the user of this hidden lines feature as soon as he copies a snippet. It could trigger on a click or on a selection. A cookie (as cookies are already used for themes) can make sure the warning is displayed only once in timespan.
This issue looks similar to #263 ?
I copy paste the feedback from the reddit link (in case the post is deleted):
I guess it depends on who this is catered to. I'm super new and I've never touched c or c++ before.
- I didn't realize the two arrows showed hidden code at all until people told me that here. After that it took me a while to figure out to import the error crate with a "-" rather than a "_" in the toml file, I'm still not sure why it's different in the cargo.toml file and the main.rs file
- So if this is catering to total newbies I think it would be a good idea to not only list the full code, but also a shot at the cargo.toml
- Even for intermediate users I wonder if the hidden code is really that obvious to them.
Yep its a duplicate of #263 by @isaacg1 . Ive copied the highlights from it and closed the older issue to give the problem a little more priority.
I didn't see the error chain information, I apologize. With that in mind, I see that the code doesn't need to be changed. That being said, I do think it's very easy to completely miss the fact that the error handling information is present, since the natural workflow is Table of Contents -> Basics or another specific topic, without ever looking at the About area, and the expand button in the top right is small and subtle. I think it would help if it was more clear that the elements should not be copy-pasted as is, only after expanding. Maybe clicking/highlighting the code should expand the box as well?
Thanks for taking initiative @Phaiax and @ludwigpacifici and good ideas! Originally I was thinking about:
- having some onetime popup pointing to the snippet buttonbar with explanations
- possibly blinking the buttons on load (on first load/on snippet hover?)
- expanding the snippet on click (I guess would avoid doing it on hover)
A cookie (as cookies are already used for themes)
Actually mdbook uses store.js for themes (local storage with cookie fallback)
Would you be interested in working on a POC for such notification mechanism @Phaiax?
If we manage to find a satisfying solution we can always backport it to mdbook.
how about "how to navigate" on top of main page?
That along with some improvement on each snippet might be the best course of action The expand button is explained deep down in the about.html -> a note about error handling which is probably skipped by 99% of the readers...
Why not make the hidden text selectable and copyable? Then, readers who are not familiar with the icons (copy, run and expand code) can still use the default (and widely used) copy/paste and it will work when pasted into the editor/IDE.
Example from the stackoverflow link
Html:
<div>
This is visible.
<span class="hidden">This is not.</span>
(Copy and paste this to see the hidden line)
</div>
Css:
div {
color: #000;
background-color: #FFF;
}
.hidden{
/* Transparent text, should work on any background colour */
color: rgba(0,0,0,0);
font-size: 0;
}
trying to use this with hljs might be more than tricky but with clipboard.js (that we already use for copy button) we might be able to modify users selection buffer (personally I'd prefer just auto expanding of the whole snippet if user stsrts to click/select as it would be less intrusive).
More basic question: is it actually necessary to have two version of the examples at all? It would be vastly simpler to have just one and in the samples that i looked at, the only difference seemed to be error_chain code, which could be removed just by switching to the two argument version of Result (which would also probably be less confusing to new users).
@fintelia there is always a tradeoff between conciseness and ergonomy. While the mentioned std example would yield to that reasoning, in most multi-crate examples (or even single-crate +std ones) where error boilerplate without error_chain would be longer than the example itself. And this verbose and almost identical boilerplate would be repeated 70+ times throughout the cookbook.
But yeah, certainly a problem in current setup.
about.html is probably skipped by most people. we probably should make a shorter version. sth like this: https://jaroslaw-weber.github.io/cookbook-new-design/generated/index.html (how to navigate part)
Just wanted to chime in on this thread as someone who just started playing with Rust today. I used a Google search to find a sample in the cookbook https://rust-lang-nursery.github.io/rust-cookbook/file/dir.html#recursively-find-all-files-with-given-predicate - I used the copy button, but was alarmed to see that the text didn't match what I saw in the browser. I figured this was a bug. So I used the mouse to copy and paste, and then got an error "expected 2 type arguments" when compiling it. I initially thought perhaps the sample was out of date. I then tried the copy button again and it worked, but it was super confusing.
When I was looking at filing a bug on this, I found this bug instead, and now I understand why I needed to use the copy button and read the about.html. But I definitely skipped the about.html, why would I read this when I had what I thought was the right code in front of me to just copy and paste. Possible suggestions would be to (1) include a warning if you try to manually copy and paste with more information about what is going on, or (2) show the full code in the browser, or (3) if you copy and paste, then copy over the full and non-abbreviated code.
Honestly, there's only a few recipes that hiding the boilerplate adds a huge value. I've certainly heard more problems with the hidden-by-default nature. I thought most of it would be solved by removing the recipes that don't leverage most of error-chains features, but it sounds like option 2 makes a lot of sense now.
@Darksonn I've started the process, and I just need somebody to finish it up https://github.com/rust-lang-nursery/rust-cookbook/pull/564