Replace hyphens (-) with em-dashes (—) (#1500)

The new Chromium class likes — like me! — to use dashes in the writing!
However, I believe it should use an em-dash instead of the hyphen.

Luckily this is easy: we have enabled “typographic quotes” in `mdbook`,
which also handles the conversion of `---` to `—` in the generated HTML.
So I normalized the single existing em-dash to a triple-dash to make it
more consistent (and hopefully make it easier for translators to
consistently enter these characters).

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 

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.
-</details>
+</details>

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

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`.
 
 <details>
-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.
+
 </detail>
 
-[0]: https://doc.rust-lang.org/cargo/reference/semver.html
+[0]: https://doc.rust-lang.org/cargo/reference/semver.html

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/<crate>` -
 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`.

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
+[3]: https://chromium.googlesource.com/chromium/src/+/main/docs/security/rule-of-2.md#unsafe-code-in-safe-languages

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.
 <details>
 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.
 </details>
 
-[0]: https://gn.googlesource.com/gn/+/main/docs/reference.md#func_static_library
+[0]: https://gn.googlesource.com/gn/+/main/docs/reference.md#func_static_library

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
-}
+}

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.
 
 <details>
+
 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`.
+
 </details>
 
 [0]: https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/rust.md#Using-cargo
 [1]: https://rustup.rs/
-[2]: https://crates.io/
+[2]: https://crates.io/

src/chromium/interoperability-with-cpp.md

@@ -17,9 +17,11 @@ See the [CXX tutorial][1] for a full example of using this.
 
 
 <details>
+
 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".
-</details>
+
+</details>

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.
 
-</details>
+</details>

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].
 
 <details>
-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.
+
 </details>
 
 [0]: https://source.chromium.org/chromium/chromium/src/+/main:base/containers/span_rust.h;l=21
-[1]: https://steveklabnik.com/writing/the-cxx-debate
+[1]: https://steveklabnik.com/writing/the-cxx-debate

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.
+catch up in the next slot.

src/concurrency/shared_state/mutex.md

@@ -28,12 +28,12 @@ implementation.
 
 <details>
     
-* `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<T>` by taking the lock. The `MutexGuard` ensures that the
   `&mut T` doesn't outlive the lock being held.
 * `Mutex<T>` 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

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

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.

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.

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))
 

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.