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 |
 

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

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,7 +24,7 @@ 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

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.
 

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

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,6 +45,7 @@ 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

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>

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

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,9 +33,10 @@ 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

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.

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.