docs: Switch the guide to use smart punctuation.

ehuss · ehuss · commit 89878519b46a · 2024-05-13T13:43:04.000-07:00
diff --git a/guide/book.toml b/guide/book.toml
@@ -8,6 +8,7 @@ language = "en"
 edition = "2018"
 
 [output.html]
+smart-punctuation = true
 mathjax-support = true
 site-url = "/mdBook/"
 git-repository-url = "https://github.com/rust-lang/mdBook/tree/master/guide"
diff --git a/guide/src/cli/README.md b/guide/src/cli/README.md
@@ -5,10 +5,10 @@ After you have [installed](../guide/installation.md) `mdbook`, you can run the `
 
 This following sections provide in-depth information on the different commands available.
 
-* [`mdbook init <directory>`](init.md) — Creates a new book with minimal boilerplate to start with.
-* [`mdbook build`](build.md) — Renders the book.
-* [`mdbook watch`](watch.md) — Rebuilds the book any time a source file changes.
-* [`mdbook serve`](serve.md) — Runs a web server to view the book, and rebuilds on changes.
-* [`mdbook test`](test.md) — Tests Rust code samples.
-* [`mdbook clean`](clean.md) — Deletes the rendered output.
-* [`mdbook completions`](completions.md) — Support for shell auto-completion.
+* [`mdbook init <directory>`](init.md) --- Creates a new book with minimal boilerplate to start with.
+* [`mdbook build`](build.md) --- Renders the book.
+* [`mdbook watch`](watch.md) --- Rebuilds the book any time a source file changes.
+* [`mdbook serve`](serve.md) --- Runs a web server to view the book, and rebuilds on changes.
+* [`mdbook test`](test.md) --- Tests Rust code samples.
+* [`mdbook clean`](clean.md) --- Deletes the rendered output.
+* [`mdbook completions`](completions.md) --- Support for shell auto-completion.
diff --git a/guide/src/cli/build.md b/guide/src/cli/build.md
@@ -22,12 +22,12 @@ root instead of the current working directory.
 mdbook build path/to/book
 ```
 
-#### --open
+#### `--open`
 
 When you use the `--open` (`-o`) flag, mdbook will open the rendered book in
 your default web browser after building it.
 
-#### --dest-dir
+#### `--dest-dir`
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
 book. Relative paths are interpreted relative to the book's root directory. If
diff --git a/guide/src/cli/clean.md b/guide/src/cli/clean.md
@@ -16,7 +16,7 @@ root instead of the current working directory.
 mdbook clean path/to/book
 ```
 
-#### --dest-dir
+#### `--dest-dir`
 
 The `--dest-dir` (`-d`) option allows you to override the book's output
 directory, which will be deleted by this command. Relative paths are interpreted
@@ -27,4 +27,4 @@ value of the `build.build-dir` key in `book.toml`, or to `./book`.
 mdbook clean --dest-dir=path/to/book
 ```
 
-`path/to/book` could be absolute or relative.
+`path/to/book` could be absolute or relative.
diff --git a/guide/src/cli/init.md b/guide/src/cli/init.md
@@ -45,15 +45,15 @@ instead of the current working directory.
 mdbook init path/to/book
 ```
 
-#### --theme
+#### `--theme`
 
 When you use the `--theme` flag, the default theme will be copied into a
 directory called `theme` in your source directory so that you can modify it.
 
 The theme is selectively overwritten, this means that if you don't want to
 overwrite a specific file, just delete it and the default file will be used.
 
-#### --title
+#### `--title`
 
 Specify a title for the book. If not supplied, an interactive prompt will ask for 
 a title. 
@@ -62,7 +62,7 @@ a title.
 mdbook init --title="my amazing book"
 ```
 
-#### --ignore
+#### `--ignore`
 
 Create a `.gitignore` file configured to ignore the `book` directory created when [building] a book. 
 If not supplied, an interactive prompt will ask whether it should be created.
@@ -77,6 +77,6 @@ mdbook init --ignore=git
 
 [building]: build.md
 
-#### --force
+#### `--force`
 
 Skip the prompts to create a `.gitignore` and for the title for the book.
diff --git a/guide/src/cli/serve.md b/guide/src/cli/serve.md
@@ -32,12 +32,12 @@ The `serve` hostname defaults to `localhost`, and the port defaults to `3000`. E
 mdbook serve path/to/book -p 8000 -n 127.0.0.1 
 ```
 
-#### --open
+#### `--open`
 
 When you use the `--open` (`-o`) flag, mdbook will open the book in your
 default web browser after starting the server.
 
-#### --dest-dir
+#### `--dest-dir`
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
 book. Relative paths are interpreted relative to the book's root directory. If
diff --git a/guide/src/cli/test.md b/guide/src/cli/test.md
@@ -37,7 +37,7 @@ instead of the current working directory.
 mdbook test path/to/book
 ```
 
-#### --library-path
+#### `--library-path`
 
 The `--library-path` (`-L`) option allows you to add directories to the library
 search path used by `rustdoc` when it builds and tests the examples. Multiple
@@ -54,14 +54,14 @@ mdbook test my-book -L target/debug/deps/
 See the `rustdoc` command-line [documentation](https://doc.rust-lang.org/rustdoc/command-line-arguments.html#-l--library-path-where-to-look-for-dependencies)
 for more information.
 
-#### --dest-dir
+#### `--dest-dir`
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
 book. Relative paths are interpreted relative to the book's root directory. If
 not specified it will default to the value of the `build.build-dir` key in
 `book.toml`, or to `./book`.
 
-#### --chapter
+#### `--chapter`
 
 The `--chapter` (`-c`) option allows you to test a specific chapter of the
 book using the chapter name or the relative path to the chapter.
diff --git a/guide/src/cli/watch.md b/guide/src/cli/watch.md
@@ -15,12 +15,12 @@ root instead of the current working directory.
 mdbook watch path/to/book
 ```
 
-#### --open
+#### `--open`
 
 When you use the `--open` (`-o`) option, mdbook will open the rendered book in
 your default web browser.
 
-#### --dest-dir
+#### `--dest-dir`
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
 book. Relative paths are interpreted relative to the book's root directory. If
diff --git a/guide/src/continuous-integration.md b/guide/src/continuous-integration.md
@@ -51,13 +51,13 @@ cargo install mdbook --no-default-features --features search --vers "^0.4" --loc
 
 This includes several recommended options:
 
-* `--no-default-features` — Disables features like the HTTP server used by `mdbook serve` that is likely not needed on CI.
+* `--no-default-features` --- Disables features like the HTTP server used by `mdbook serve` that is likely not needed on CI.
   This will speed up the build time significantly.
-* `--features search` — Disabling default features means you should then manually enable features that you want, such as the built-in [search] capability.
-* `--vers "^0.4"` — This will install the most recent version of the `0.4` series.
+* `--features search` --- Disabling default features means you should then manually enable features that you want, such as the built-in [search] capability.
+* `--vers "^0.4"` --- This will install the most recent version of the `0.4` series.
   However, versions after like `0.5.0` won't be installed, as they may break your build.
   Cargo will automatically upgrade mdBook if you have an older version already installed.
-* `--locked` — This will use the dependencies that were used when mdBook was released.
+* `--locked` --- This will use the dependencies that were used when mdBook was released.
   Without `--locked`, it will use the latest version of all dependencies, which may include some fixes since the last release, but may also (rarely) cause build problems.
 
 You will likely want to investigate caching options, as building mdBook can be somewhat slow.
diff --git a/guide/src/format/configuration/general.md b/guide/src/format/configuration/general.md
@@ -72,7 +72,7 @@ edition = "2015"   # the default edition for code blocks
 ```
 
 - **edition**: Rust edition to use by default for the code snippets. Default
-  is "2015". Individual code blocks can be controlled with the `edition2015`, 
+  is `"2015"`. Individual code blocks can be controlled with the `edition2015`,
   `edition2018` or `edition2021` annotations, such as:
 
   ~~~text
diff --git a/guide/src/format/configuration/renderers.md b/guide/src/format/configuration/renderers.md
@@ -4,9 +4,9 @@ Renderers (also called "backends") are responsible for creating the output of th
 
 The following backends are built-in:
 
-* [`html`](#html-renderer-options) — This renders the book to HTML.
+* [`html`](#html-renderer-options) --- This renders the book to HTML.
   This is enabled by default if no other `[output]` tables are defined in `book.toml`.
-* [`markdown`](#markdown-renderer) — This outputs the book as markdown after running the preprocessors.
+* [`markdown`](#markdown-renderer) --- This outputs the book as markdown after running the preprocessors.
   This is useful for debugging preprocessors.
 
 The community has developed several backends.
@@ -120,7 +120,7 @@ The following configuration options are available:
   'Change Theme' dropdown. Defaults to `light`.
 - **preferred-dark-theme:** The default dark theme. This theme will be used if
   the browser requests the dark version of the site via the
-  ['prefers-color-scheme'](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
+  [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
   CSS media query. Defaults to `navy`.
 - **smart-punctuation:** Converts quotes to curly quotes, `...` to `…`, `--` to en-dash, and `---` to em-dash.
   See [Smart Punctuation].
diff --git a/guide/src/format/mdbook.md b/guide/src/format/mdbook.md
@@ -112,16 +112,16 @@ panic!("oops!");
 These are particularly important when using [`mdbook test`] to test Rust examples.
 These use the same attributes as [rustdoc attributes], with a few additions:
 
-* `editable` — Enables the [editor].
-* `noplayground` — Removes the play button, but will still be tested.
-* `mdbook-runnable` — Forces the play button to be displayed.
+* `editable` --- Enables the [editor].
+* `noplayground` --- Removes the play button, but will still be tested.
+* `mdbook-runnable` --- Forces the play button to be displayed.
   This is intended to be combined with the `ignore` attribute for examples that should not be tested, but you want to allow the reader to run.
-* `ignore` — Will not be tested and no play button is shown, but it is still highlighted as Rust syntax.
-* `should_panic` — When executed, it should produce a panic.
-* `no_run` — The code is compiled when tested, but it is not run.
+* `ignore` --- Will not be tested and no play button is shown, but it is still highlighted as Rust syntax.
+* `should_panic` --- When executed, it should produce a panic.
+* `no_run` --- The code is compiled when tested, but it is not run.
   The play button is also not shown.
-* `compile_fail` — The code should fail to compile.
-* `edition2015`, `edition2018`, `edition2021` — Forces the use of a specific Rust edition.
+* `compile_fail` --- The code should fail to compile.
+* `edition2015`, `edition2018`, `edition2021` --- Forces the use of a specific Rust edition.
   See [`rust.edition`] to set this globally.
 
 [`mdbook test`]: ../cli/test.md
diff --git a/guide/src/format/theme/index-hbs.md b/guide/src/format/theme/index-hbs.md
@@ -18,7 +18,7 @@ handlebars template you can access this information by using
 Here is a list of the properties that are exposed:
 
 - ***language*** Language of the book in the form `en`, as specified in `book.toml` (if not specified, defaults to `en`). To use in <code
-  class="language-html">\<html lang="{{ language }}"></code> for example.
+  class="language-html">\<html lang=\"{{ language }}\"></code> for example.
 - ***title*** Title used for the current page. This is identical to `{{ chapter_title }} - {{ book_title }}` unless `book_title` is not set in which case it just defaults to the `chapter_title`.
 - ***book_title*** Title of the book, as specified in `book.toml`
 - ***chapter_title*** Title of the current chapter, as listed in `SUMMARY.md`
