diff --git a/src/basic-syntax/compound-types.md b/src/basic-syntax/compound-types.md
index adf78b63..aab46a68 100644
--- a/src/basic-syntax/compound-types.md
+++ b/src/basic-syntax/compound-types.md
@@ -55,7 +55,7 @@ Tuples:
* Fields of a tuple can be accessed by the period and the index of the value, e.g. `t.0`, `t.1`.
* The empty tuple `()` is also known as the "unit type". It is both a type, and
- the only valid value of that type - that is to say both the type and its value
+ the only valid value of that type --- that is to say both the type and its value
are expressed as `()`. It is used to indicate, for example, that a function or
expression has no return value, as we'll see in a future slide.
* You can think of it as `void` that can be familiar to you from other
diff --git a/src/chromium/adding-third-party-crates.md b/src/chromium/adding-third-party-crates.md
index 0dbd24e2..b4668108 100644
--- a/src/chromium/adding-third-party-crates.md
+++ b/src/chromium/adding-third-party-crates.md
@@ -5,7 +5,7 @@ easy* for Rust crates to depend upon one another. So they do!
| Property | C++ library | Rust crate |
| --- | --- | --- |
-| Build system | Lots | Consistent - `Cargo.toml` |
+| Build system | Lots | Consistent: `Cargo.toml` |
| Typical library size | Large-ish | Small |
| Transitive dependencies | Few | Lots |
@@ -29,4 +29,4 @@ All of the things in the table on this slide are generalizations, and
counter-examples can be found. But in general it's important for students
to understand that most Rust code depends on other Rust libraries, because
it's easy to do so, and that this has both benefits and costs.
-
\ No newline at end of file
+
diff --git a/src/chromium/adding-third-party-crates/configuring-cargo-toml.md b/src/chromium/adding-third-party-crates/configuring-cargo-toml.md
index 86aa1764..ad43cae2 100644
--- a/src/chromium/adding-third-party-crates/configuring-cargo-toml.md
+++ b/src/chromium/adding-third-party-crates/configuring-cargo-toml.md
@@ -12,7 +12,7 @@ cxx = "1"
```
As with any other `Cargo.toml`, you can specify [more details about
-the dependencies][1] - most commonly, you'll want to specify the `features` that
+the dependencies][1] --- most commonly, you'll want to specify the `features` that
you wish to enable in the crate.
When adding a crate to Chromium, you'll often need to provide some extra
diff --git a/src/chromium/adding-third-party-crates/generating-gn-build-rules.md b/src/chromium/adding-third-party-crates/generating-gn-build-rules.md
index 9350851d..b1cc2468 100644
--- a/src/chromium/adding-third-party-crates/generating-gn-build-rules.md
+++ b/src/chromium/adding-third-party-crates/generating-gn-build-rules.md
@@ -17,9 +17,11 @@ The "major semver version" is a [Rust "semver" version number][0].
Take a close look, especially at the things generated in `third_party/rust`.
-Talk a little about semver - and specifically the way that in Chromium
+
+Talk a little about semver --- and specifically the way that in Chromium
it's to allow multiple incompatible versions of a crate, which is discouraged
but sometimes necessary in the cargo ecosystem.
+
-[0]: https://doc.rust-lang.org/cargo/reference/semver.html
\ No newline at end of file
+[0]: https://doc.rust-lang.org/cargo/reference/semver.html
diff --git a/src/chromium/adding-third-party-crates/resolving-problems/build-scripts-which-take-arbitrary-actions.md b/src/chromium/adding-third-party-crates/resolving-problems/build-scripts-which-take-arbitrary-actions.md
index cebfe7fc..65eb93c1 100644
--- a/src/chromium/adding-third-party-crates/resolving-problems/build-scripts-which-take-arbitrary-actions.md
+++ b/src/chromium/adding-third-party-crates/resolving-problems/build-scripts-which-take-arbitrary-actions.md
@@ -2,7 +2,7 @@
Some crates use the [`cc`][2] crate to build and link C/C++ libraries.
Other crates parse C/C++ using [`bindgen`][3] within their build scripts.
-These actions can't be supported in a Chromium context - our gn, ninja
+These actions can't be supported in a Chromium context --- our gn, ninja
and LLVM build system is very specific in expressing relationships between
build actions.
@@ -13,7 +13,7 @@ So, your options are:
Patches should be kept in `third_party/rust/chromium_crates_io/patches/` -
see for example the [patches against the cxx crate][4]. There is currently
-no automation - [simply create and apply patches manually][5] to remove the
+no automation --- [simply create and apply patches manually][5] to remove the
problematic actions from the build script.
If your patches modify the `Cargo.toml` file, rerun `gnrt gen`.
diff --git a/src/chromium/adding-third-party-crates/reviews-and-audits.md b/src/chromium/adding-third-party-crates/reviews-and-audits.md
index e69dde23..8b9858be 100644
--- a/src/chromium/adding-third-party-crates/reviews-and-audits.md
+++ b/src/chromium/adding-third-party-crates/reviews-and-audits.md
@@ -24,10 +24,10 @@ Meanwhile, for each new crate addition, we are checking for the following:
that might have been maliciously inserted. (You can't realistically aim
for 100% perfection here: there's often just too much code.)
-These are just guidelines - work with reviewers from `security@chromium.org`
+These are just guidelines --- work with reviewers from `security@chromium.org`
to work out the right way to become confident of the crate.
[0]: https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/rust.md#Third_party-review
[1]: https://mozilla.github.io/cargo-vet/
[2]: ../cargo.md
-[3]: https://chromium.googlesource.com/chromium/src/+/main/docs/security/rule-of-2.md#unsafe-code-in-safe-languages
\ No newline at end of file
+[3]: https://chromium.googlesource.com/chromium/src/+/main/docs/security/rule-of-2.md#unsafe-code-in-safe-languages
diff --git a/src/chromium/build-rules.md b/src/chromium/build-rules.md
index e0c31daa..41365bf0 100644
--- a/src/chromium/build-rules.md
+++ b/src/chromium/build-rules.md
@@ -1,7 +1,7 @@
# Build rules
Rust code is usually built using `cargo`. Chromium builds with `gn` and `ninja`
-for efficiency - its static rules allow maximum parallelism. Rust is no exception.
+for efficiency --- its static rules allow maximum parallelism. Rust is no exception.
## Adding Rust code to Chromium
@@ -22,7 +22,7 @@ depend upon third party code.
You must specify _both_ the crate root, _and_ a full list of sources.
The `crate_root` is the file given to the Rust compiler representing the root
-file of the compilation unit - typically `lib.rs`. `sources` is a complete
+file of the compilation unit --- typically `lib.rs`. `sources` is a complete
list of all source files which `ninja` needs in order to determine when rebuilds
are necessary.
@@ -35,4 +35,4 @@ The answer is that this template provides support for cxx interop, Rust features
and unit tests, some of which we'll use later.
-[0]: https://gn.googlesource.com/gn/+/main/docs/reference.md#func_static_library
\ No newline at end of file
+[0]: https://gn.googlesource.com/gn/+/main/docs/reference.md#func_static_library
diff --git a/src/chromium/build-rules/unsafe.md b/src/chromium/build-rules/unsafe.md
index 505d9af8..6e62afc6 100644
--- a/src/chromium/build-rules/unsafe.md
+++ b/src/chromium/build-rules/unsafe.md
@@ -1,6 +1,6 @@
# Including `unsafe` Rust code
-Unsafe Rust code is forbidden in `rust_static_library` by default - it won't
+Unsafe Rust code is forbidden in `rust_static_library` by default --- it won't
compile. If you need unsafe Rust code, add `allow_unsafe = true` to the
gn target. (Later in the course we'll see circumstances where this is necessary.)
@@ -14,4 +14,4 @@ rust_static_library("my_rust_lib") {
"hippopotamus.rs"
]
allow_unsafe = true
-}
\ No newline at end of file
+}
diff --git a/src/chromium/cargo.md b/src/chromium/cargo.md
index e5bf6f7b..9ac41e9e 100644
--- a/src/chromium/cargo.md
+++ b/src/chromium/cargo.md
@@ -35,8 +35,9 @@ Discuss in small groups the policies within your own team and organization,
and come to a group agreement about what's an acceptable level of risk.
+
Explain that it might seem strange to write tools in Rust, but this is
-increasingly popular across the industry - Rust tools are quicker and work
+increasingly popular across the industry --- Rust tools are quicker and work
more reliably.
Assuming folks taking the course are physically together, ask them to discuss
@@ -44,8 +45,9 @@ in small groups of 3-4 people. Then, ask each table whether they've come
to a consensus on the level of risk.
Later in the course, we'll be running an actual `cargo`-based tool, `gnrt`.
+
[0]: https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/rust.md#Using-cargo
[1]: https://rustup.rs/
-[2]: https://crates.io/
\ No newline at end of file
+[2]: https://crates.io/
diff --git a/src/chromium/interoperability-with-cpp.md b/src/chromium/interoperability-with-cpp.md
index 7367863b..b93ab874 100644
--- a/src/chromium/interoperability-with-cpp.md
+++ b/src/chromium/interoperability-with-cpp.md
@@ -17,9 +17,11 @@ See the [CXX tutorial][1] for a full example of using this.
+
Talk through the diagram. Explain that behind the scenes, this is doing
-just the same as you previously did - but by programmatically ensuring that
+just the same as you previously did --- but by programmatically ensuring that
the C++ and Rust sides match, cxx can ensure there aren't obvious errors
with object lifetimes, string lengths, etc. It reduces lots of fiddly
boilerplate and the resulting code feels more "natural".
-
\ No newline at end of file
+
+
diff --git a/src/chromium/interoperability-with-cpp/limitations-of-cxx.md b/src/chromium/interoperability-with-cpp/limitations-of-cxx.md
index 022086d9..c72026c7 100644
--- a/src/chromium/interoperability-with-cpp/limitations-of-cxx.md
+++ b/src/chromium/interoperability-with-cpp/limitations-of-cxx.md
@@ -8,7 +8,7 @@ cxx fundamentally suits cases where:
* You're using only the types natively supported by cxx already, for example
`std::unique_ptr`, `std::string`, `&[u8]` etc.
-It has many limitations - for example lack of support for Rust's `Option` type.
+It has many limitations --- for example lack of support for Rust's `Option` type.
These limitations constrain us to using Rust in Chromium only for well isolated
"leaf nodes" rather than for arbitrary Rust-C++ interop. When considering
@@ -28,4 +28,4 @@ You should also discuss some of the other sticky points with cxx, for example:
* Its error handling is based around C++ exceptions (given on the next slide)
* Function pointers are awkward to use.
-
\ No newline at end of file
+
diff --git a/src/chromium/interoperability-with-cpp/using-cxx-in-chromium.md b/src/chromium/interoperability-with-cpp/using-cxx-in-chromium.md
index 8df5fc4f..193f02d1 100644
--- a/src/chromium/interoperability-with-cpp/using-cxx-in-chromium.md
+++ b/src/chromium/interoperability-with-cpp/using-cxx-in-chromium.md
@@ -20,10 +20,11 @@ C++ headers will be generated at a sensible location, so you can just
```
You will find some utility functions in `//base` to convert to/from Chromium
-C++ types to cxx Rust types - for example [`SpanToRustSlice`][0].
+C++ types to cxx Rust types --- for example [`SpanToRustSlice`][0].
-Students may ask - why do we still need `allow_unsafe = true`?
+
+Students may ask --- why do we still need `allow_unsafe = true`?
The broad answer is that no C/C++ code is "safe" by the normal Rust standards.
Calling back and forth to C/C++ from Rust may do arbitrary things to memory, and
@@ -32,10 +33,11 @@ compromise the safety of Rust's own data layouts. Presence of _too many_
such a keyword, and is [controversial][1], but strictly, bringing any foreign
code into a Rust binary can cause unexpected behavior from Rust's perspective.
-The narrow answer lies in the diagram at the top of this page - behind the
+The narrow answer lies in the diagram at the top of this page --- behind the
scenes, cxx generates Rust `unsafe` and `extern "C"` functions just like
we did manually in the previous section.
+
[0]: https://source.chromium.org/chromium/chromium/src/+/main:base/containers/span_rust.h;l=21
-[1]: https://steveklabnik.com/writing/the-cxx-debate
\ No newline at end of file
+[1]: https://steveklabnik.com/writing/the-cxx-debate
diff --git a/src/chromium/setup.md b/src/chromium/setup.md
index b9aad989..e1dcaab5 100644
--- a/src/chromium/setup.md
+++ b/src/chromium/setup.md
@@ -14,7 +14,7 @@ out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium
is the default!)
See [How to build Chromium](https://www.chromium.org/developers/how-tos/get-the-code/)
-if you aren't already at that point. Be warned - setting up to build Chromium
+if you aren't already at that point. Be warned: setting up to build Chromium
takes time.
It's also recommended that you have Visual Studio code installed.
@@ -24,4 +24,4 @@ It's also recommended that you have Visual Studio code installed.
This part of the course has a series of exercises which build on each other.
We'll be doing them spread throughout the course instead of just at the end.
If you don't have time to complete a certain part, don't worry: you can
-catch up in the next slot.
\ No newline at end of file
+catch up in the next slot.
diff --git a/src/concurrency/shared_state/mutex.md b/src/concurrency/shared_state/mutex.md
index 8fc7d45f..7bd2224f 100644
--- a/src/concurrency/shared_state/mutex.md
+++ b/src/concurrency/shared_state/mutex.md
@@ -28,12 +28,12 @@ implementation.
-* `Mutex` in Rust looks like a collection with just one element - the protected data.
+* `Mutex` in Rust looks like a collection with just one element --- the protected data.
* It is not possible to forget to acquire the mutex before accessing the protected data.
* You can get an `&mut T` from an `&Mutex` by taking the lock. The `MutexGuard` ensures that the
`&mut T` doesn't outlive the lock being held.
* `Mutex` implements both `Send` and `Sync` iff (if and only if) `T` implements `Send`.
-* A read-write lock counterpart - `RwLock`.
+* A read-write lock counterpart: `RwLock`.
* Why does `lock()` return a `Result`?
* If the thread that held the `Mutex` panicked, the `Mutex` becomes "poisoned" to signal that
the data it protected might be in an inconsistent state. Calling `lock()` on a poisoned mutex
diff --git a/src/concurrency/threads.md b/src/concurrency/threads.md
index 6ba67e14..53ae24b2 100644
--- a/src/concurrency/threads.md
+++ b/src/concurrency/threads.md
@@ -29,7 +29,7 @@ fn main() {
Key points:
-* Notice that the thread is stopped before it reaches 10 — the main thread is
+* Notice that the thread is stopped before it reaches 10 --- the main thread is
not waiting.
* Use `let handle = thread::spawn(...)` and later `handle.join()` to wait for
diff --git a/src/exercises/chromium/bringing-it-together.md b/src/exercises/chromium/bringing-it-together.md
index 08549304..052c8f36 100644
--- a/src/exercises/chromium/bringing-it-together.md
+++ b/src/exercises/chromium/bringing-it-together.md
@@ -1,4 +1,4 @@
-# Bringing it together - Exercise
+# Bringing it together --- Exercise
In this exercise, you're going to add a whole new Chromium feature, bringing
together everything you already learned.
diff --git a/src/exercises/concurrency/dining-philosophers-async.md b/src/exercises/concurrency/dining-philosophers-async.md
index 611c1c93..71450e76 100644
--- a/src/exercises/concurrency/dining-philosophers-async.md
+++ b/src/exercises/concurrency/dining-philosophers-async.md
@@ -1,4 +1,4 @@
-# Dining Philosophers - Async
+# Dining Philosophers --- Async
See [dining philosophers](dining-philosophers.md) for a description of the
problem.
diff --git a/src/exercises/concurrency/solutions-afternoon.md b/src/exercises/concurrency/solutions-afternoon.md
index 4dfa5831..959a68f6 100644
--- a/src/exercises/concurrency/solutions-afternoon.md
+++ b/src/exercises/concurrency/solutions-afternoon.md
@@ -1,6 +1,6 @@
# Concurrency Afternoon Exercise
-## Dining Philosophers - Async
+## Dining Philosophers --- Async
([back to exercise](dining-philosophers-async.md))
diff --git a/src/running-the-course/course-structure.md b/src/running-the-course/course-structure.md
index 522f9c7e..395546df 100644
--- a/src/running-the-course/course-structure.md
+++ b/src/running-the-course/course-structure.md
@@ -41,7 +41,7 @@ Rust as part of the Chromium browser. It includes using Rust in Chromium's
`gn` build system, bringing in third-party libraries ("crates") and C++
interoperability.
-You will need to be able to build Chromium - a debug, component build is
+You will need to be able to build Chromium --- a debug, component build is
[recommended](../chromium/setup.md) for speed but any build will work.
Ensure that you can run the Chromium browser that you've built.