* Generalize the day-4 afternoon
This is in preparation for adding more options for this portion of the
course, and reflects an existing practice of substituting other
materials for this last half-day.
* address review comments
* Add note about requesting a room with tables
The course is built on the idea of using live-coding as much as possible. This means that it's important that there are desks in the classrooms — a traditional auditorium setup does not work well.
* Update book-library.md
* Update book-library.rs
* Apply suggestions from code review
Expanding the variable makes it ever-so-slightly easier to read.
---------
Co-authored-by: Martin Geisler <mgeisler@google.com>
The slide is way too large to comfortable use in a classroom. Instead
of printing six lines of output, the instructor should carefully walk
through the different examples. That way we can take the course
participants with us through the explanations instead of simply
showing them the end result.
* Further simplify `Box` diagrams
I think we can improve the drawing by simplifying them and making them
more symbolic. Followup to #374.
* Apply suggestions from code review
Example contained unnecessary explicit type info for the vector in Mutex v. Rust will magically do the needful conversions for us. Code looks cleaner/simpler without the explicit typing.
* Update match-expressions.md
* Apply suggestions from code review
Fine tuning the casing and explanations.
---------
Co-authored-by: Martin Geisler <mgeisler@google.com>
* Suggesting to add `Default` to important traits.
This is a great trait to know about, it is used very often.
* Change `Implemented` to tuple struct.
It saves vertical space.
* Move Cargo.toml for exercises to exercises directory.
* Create a workspace with both exercises and i18n-helpers.
* Build in CI as well as testing.
* Binaries must have a main function.
* No need for workspaces configuration for caching anymore.
The code is probably meant to illustrate the `vec!` macro, but it
feels out of place when teaching: there is already enough material
here to get through.
* Update unsafe.md
Adding a paragraph explaining that unsafe code is not necessary broken or evil, but it is a mode
where compiler safety features are off.
* Move explanation to speaker notes
To avoid slide being too long. Also edited text slightly.
* Remove extra space
---------
Co-authored-by: Andrew Walbran <qwandor@google.com>
* Update unit tests to use generic perimeter
* Update solution to use perimeter
Update solution to use the generic term perimeter instead of circumference
* Corrections around slices and string slices, also slight improvements to the language.
* Explained some of the confusing details in the functions example.
* Added a speaker note (hinting at `Into` as a complement to generics).
* Exclude the clarification code snippet from build testing.
* Update functions-interlude.md
Do not mention explicit section numbers as they may change.
* Update string-slices.md
* Adding an extra example of converting `String` back to `&str`.
* C++ who would often read this guide could get immediate intuitive understanding of Rust strings if you compare them to C++ equivalents.
* Expand on `String` vs `std::string`
Co-authored-by: Martin Geisler <martin@geisler.net>
* Update lifetimes-function-calls.md
I am trying to describe the problem lifetimes solve. It may seem they are complex and useless, but the paragraph starts from the problem Rust cannot
solve on it's own (yet). Then the paragraph illustrates the problem represented in the code and how lifetimes solve it.
* Update lifetimes-function-calls.md
Moving the generic explanation of why lifetimes are important to the speaker notes.
* Make language more direct
Co-authored-by: Martin Geisler <martin@geisler.net>
* Update mutex.md
Adding speaker notes why Rust `Mutex` has its design and mentioning briefly `RwLock`.
Someone from the audience can notice `unwrap()` in the code, it might be worth to have the answer in speaker notes.
* Apply suggestions from code review
Co-authored-by: Martin Geisler <martin@geisler.net>
* Update channels.md
Adding speaker notes explaining why `send` and `recv` can fail.
* Explicitly mention that the channel is closed when the sender/receiver is dropped
Co-authored-by: Martin Geisler <martin@geisler.net>
* Update result.md
Adding a speaker note that `Result` documentation is a recommended read.
* Adding a note why `Result` encourages error checking.
* Wordsmithing
Co-authored-by: Andrew Walbran <qwandor@google.com>
* Update iterator.md
Adding a Speaker Note emphasizing that all most all functional programming toolbox over collections can be found in the `Iterator` documentation.
* Wordsmithing
Co-authored-by: Andrew Walbran <qwandor@google.com>
* Update match-guards.md
Adding more information how match guards are different from simply using "if" inside of the match case, after the case has matched.
* Be consistent about naming of match arms.
Co-authored-by: Andrew Walbran <qwandor@google.com>
* Update box-recursive.md
Adding Speaker Notes. This is a high-level guideline what to say, so we can settle on one explanation and review it.
This may be very obvious with the background in some languages, but be very non-obvious in languages that always
use references and never embed structs into structs.
* Fix wording
Co-authored-by: Andrew Walbran <qwandor@google.com>
* Update if-expressions.md
Adding a note about types of `if` branch blocks.
* Fix typo and simplify.
Co-authored-by: Andrew Walbran <qwandor@google.com>
The key takeaway is mutability of receivers and the rules that come with it. It might be a repetition of borrow checker rules, but it is important to know they apply to `self` as to any other variable or argument.
* Update tuple-structs.md
I am adding more information about newtypes. The speaker can get questions about it or may wish to encourage this great pattern.
* Fix typos and explanation
Co-authored-by: Andrew Walbran <qwandor@google.com>
* Update lifetimes-data-structures.md
The example is quite simple, but in it's simplicity it may raise the question why do we even need lifetimes in the structs? Isn't it obvious that the referenced value should always outlive the struct? This sentence tries to explain that more complex cases exist.
* Fix typo
Co-authored-by: Andrew Walbran <qwandor@google.com>
Introducing `Self` type that students can encounter in many places and nice to use. It is only mentioned later in the course, but it is not defined currently.
* Update the Speaker Notes of the type-inference.md
I think this is one of the critical moments in understanding Rust. This behavior is different from many static and dynamic programming languages.
* Fix typo
Co-authored-by: Andrew Walbran <qwandor@google.com>
I suggest to clarify that you only need to implement `From` and nobody really implements `Into` as soon as `From` is implemented.
I decided to add a separate paragraph after the `i8` and `i16` example, as they provide intuitive understanding of reverse relationship between `From` and `Into`. Alternatively trying to explain `From` and `Into` in generic way sounds more confusing than just adding this sentence after the specific example.
* Update Speaker Notes for compile-time.md
The definition of memory leaks is indeed blurry, so it is important not have right expectations about this particular kind of error.
Co-authored-by: Martin Geisler <martin@geisler.net>
This implements a translation pipeline using the industry-standard
Gettext[1] system.
I picked Gettext for the reasons described in [2] and [3]:
* It’s widely used in open source software. This means that there are
graphical editors which will help you in editing the `.po` files. An
example is Poedit[4], which is available for all major platforms.
There are also many online systems for doing translations. An
example is Pontoon[5], which is used for the Rust website itself. We
can consider setting up such an instance ourselves.
* It is a light-weight yet structured format. This means that nothing
changes with regards to how you update the original English text. We
can still accept fixes and PRs like normal.
The structure means that translators can see exactly which part of
the course they need to update after a change. This is completely
lost if you simply copy over the original text and translate it
in-place in the Markdown files.
The code here only adds support for translations. They are not yet
tested, published or used for anything. Next steps will be:
* Add support for switching languages via a bit of JavaScript on each
page.
* Update the speaker notes feature to support translations (right now
“Speaker Notes” is hard-coded into the generated HTML). I think we
should turn it into a mdbook preprocessor instead.
* Add testing: We should test that the `.po` files are well-formed. We
should also run `mdbook test` on each language since the
translations can alter the embedded code.
Fixes#115.
[1]: https://www.gnu.org/software/gettext/manual/html_node/index.html
[2]: https://github.com/rust-lang/mdBook/pull/1864
[3]:
https://github.com/rust-lang/mdBook/issues/5#issuecomment-1144887806
[4]: https://poedit.net/
[5]: https://pontoon.rust-lang.org/
