jesus/mdbook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: Switch the guide to use smart punctuation.

Browse source
This commit is contained in:
Eric Huss 2024-05-13 13:43:00 -07:00
parent 83444650a3
commit 89878519b4
13 changed files with 40 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
guide/book.toml
View file

@ -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"

14
guide/src/cli/README.md
View file

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

4
guide/src/cli/build.md
View file

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

4
guide/src/cli/clean.md
View file

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

8
guide/src/cli/init.md
View file

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

4
guide/src/cli/serve.md
View file

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

6
guide/src/cli/test.md
View file

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

4
guide/src/cli/watch.md
View file

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

8
guide/src/continuous-integration.md
View file

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

2
guide/src/format/configuration/general.md
View file

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

6
guide/src/format/configuration/renderers.md
View file

@ -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].

16
guide/src/format/mdbook.md
View file

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

2
guide/src/format/theme/index-hbs.md
View file

@ -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`