Merge branch 'main' into patch-1

rust-lang · Dec 18, 2024 · b99b3f9 · b99b3f9
2 parents 0566029 + 2f61a8d
commit b99b3f9
Show file tree

Hide file tree

Showing 232 changed files with 3,838 additions and 4,034 deletions.
diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -0,0 +1,2 @@
+# Ran dprint fmt on the repo
+3a30e4c1fbe641afc066b3af9eb01dcdf5ed8b24
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -52,12 +52,8 @@ jobs:
     - name: Run `tools` package tests
       run: |
         cargo test
-    - name: Run `mdbook-trpl-note` package tests
-      working-directory: packages/mdbook-trpl-note
-      run: |
-        cargo test
-    - name: Run `mdbook-trpl-listing` package tests
-      working-directory: packages/mdbook-trpl-listing
+    - name: Run `mdbook-trpl` package tests
+      working-directory: packages/mdbook-trpl
       run: |
         cargo test
   lint:
@@ -77,10 +73,8 @@ jobs:
         mkdir bin
         curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdbook-v0.4.21-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
         echo "$(pwd)/bin" >> "${GITHUB_PATH}"
-    - name: Install mdbook-trpl-note
-      run: cargo install --path packages/mdbook-trpl-note
-    - name: Install mdbook-trpl-listing
-      run: cargo install --path packages/mdbook-trpl-listing
+    - name: Install mdbook-trpl binaries
+      run: cargo install --path packages/mdbook-trpl
     - name: Install aspell
       run: sudo apt-get install aspell
     - name: Install shellcheck

diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,5 @@ target
 tmp
 
 .nova
+.vscode
+.zed
diff --git a/ADMIN_TASKS.md b/ADMIN_TASKS.md
@@ -14,7 +14,7 @@ occasional maintenance tasks.
   does)
 - Inspect the changes (by looking at the files changed according to git) and
   their effects (by looking at the files in `tmp/book-before` and
-	`tmp/book-after`) and commit them if they look good
+  `tmp/book-after`) and commit them if they look good
 - Grep for `manual-regeneration` and follow the instructions in those places to
   update output that cannot be generated by a script
 
@@ -36,9 +36,8 @@ create a new release artifact, for example if there have been code changes due
 to edits or due to updating Rust and `rustfmt`, do the following:
 
 - Create a git tag for the release and push it to GitHub, or create a new tag
-  by going to the GitHub UI, [drafting a new
-	release](https://github.com/rust-lang/book/releases/new), and entering a new
-	tag instead of selecting an existing tag
+  by going to the GitHub UI, [drafting a new release](https://github.com/rust-lang/book/releases/new), and entering a new
+  tag instead of selecting an existing tag
 - Run `cargo run --bin release_listings`, which will generate
   `tmp/listings.tar.gz`
 - Upload `tmp/listings.tar.gz` in the GitHub UI for the draft release
@@ -54,50 +53,50 @@ extracted into a file. To do that:
 - Find where the new listing should go in the `listings` directory.
   - There is one subdirectory for each chapter
   - Numbered listings should use `listing-[chapter num]-[listing num]` for
-	  their directory names.
+    their directory names.
   - Listings without a number should start with `no-listing-` followed by a
-	  number that indicates its position in the chapter relative to the other
-		listings without numbers in the chapter, then a short description that
-		someone could read to find the code they're looking for.
+    number that indicates its position in the chapter relative to the other
+    listings without numbers in the chapter, then a short description that
+    someone could read to find the code they're looking for.
   - Listings used only for displaying the output of the code (for example, when
-	  we say "if we had written x instead of y, we would get this compiler
-		error:" but we don't actually show code x) should be named with
-		`output-only-` followed by a number that indicates its position in the
-		chapter relative to the other listings used only for output, then a short
-		description that authors or contributors could read to find the code
-		they're looking for.
+    we say "if we had written x instead of y, we would get this compiler
+    error:" but we don't actually show code x) should be named with
+    `output-only-` followed by a number that indicates its position in the
+    chapter relative to the other listings used only for output, then a short
+    description that authors or contributors could read to find the code
+    they're looking for.
   - **Remember to adjust surrounding listing numbers as appropriate!**
 - Create a full Cargo project in that directory, either by using `cargo new` or
   copying another listing as a starting point.
 - Add the code and any surrounding code needed to create a full working example.
 - If you only want to show part of the code in the file, use anchor comments
   (`// ANCHOR: some_tag` and `// ANCHOR_END: some_tag`) to mark the parts of
-	the file you want to show.
+  the file you want to show.
 - For Rust code, use the `{{#rustdoc_include [filename:some_tag]}}` directive
   within the code blocks in the text. The `rustdoc_include` directive gives the
-	code that doesn't get displayed to `rustdoc` for `mdbook test` purposes.
+  code that doesn't get displayed to `rustdoc` for `mdbook test` purposes.
 - For anything else, use the `{{#include [filename:some_tag]}}` directive.
 - If you want to display the output of a command in the text as well, create an
   `output.txt` file in the listing's directory as follows:
   - Run the command, like `cargo run` or `cargo test`, and copy all of the
-	  output.
+    output.
   - Create a new `output.txt` file with the first line `$ [the command you
 	  ran]`.
   - Paste the output you just copied.
   - Run `./tools/update-rustc.sh`, which should perform some normalization on
-	  the compiler output.
+    the compiler output.
   - Include the output in the text with the `{{#include [filename]}}` directive.
   - Add and commit output.txt.
 - If you want to display output but for some reason it can't be generated by a
   script (say, because of user input or external events like making a web
-	request), keep the output inline but make a comment that contains
-	`manual-regeneration` and instructions for manually updating the inline
-	output.
+  request), keep the output inline but make a comment that contains
+  `manual-regeneration` and instructions for manually updating the inline
+  output.
 - If you don't want this example to even be attempted to be formatted by
   `rustfmt` (for example because the example doesn't parse on purpose), add a
-	`rustfmt-ignore` file in the listing's directory and the reason it's not
-	being formatted as the contents of that file (in case it's a rustfmt bug that
-	might get fixed someday).
+  `rustfmt-ignore` file in the listing's directory and the reason it's not
+  being formatted as the contents of that file (in case it's a rustfmt bug that
+  might get fixed someday).
 
 ## See the effect of some change on the rendered book
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,6 +11,35 @@ of the print version. The snapshot files reflect what has been sent or not, so
 they only get updated when edits are sent to No Starch. **Do not submit pull
 requests changing files in the `nostarch` directory, they will be closed.**
 
+We use [`rustfmt`][rustfmt] to apply standard formatting to Rust code in the
+repo and [`dprint`][dprint] to apply standing formatting to the Markdown source
+and the non-Rust code in the project.
+
+[rustfmt]: https://github.com/rust-lang/rustfmt
+[dprint]: https://dprint.dev
+
+You will normally have `rustfmt` installed if you have a Rust toolchain
+installed; if for some reason you do not have a copy of `rustfmt`, you can add
+it by running the following command:
+
+```sh
+rustup component add rustfmt
+```
+
+To install `dprint`, you can run the following command:
+
+```sh
+cargo install dprint
+```
+
+Or follow the [instructions][install-dprint] on the `dprint` website.
+
+[install-dprint]: https://dprint.dev/install/
+
+To format Rust code, you can run `rustfmt <path to file>`, and to format other
+files, you can pass `dprint <path to file>`. Many text editors also have native
+support or extensions for both `rustfmt` and `dprint`.
+
 ## Checking for Fixes
 
 The book rides the Rust release trains. Therefore, if you see a problem on
@@ -45,8 +74,7 @@ or pull request.
 
 [nostarch]: https://nostarch.com/rust-programming-language-2nd-edition
 
-So far, we've been doing a larger revision to coincide with [Rust
-Editions](https://doc.rust-lang.org/edition-guide/). Between those larger
+So far, we've been doing a larger revision to coincide with [Rust Editions](https://doc.rust-lang.org/edition-guide/). Between those larger
 revisions, we will only be correcting errors. If your issue or pull request
 isn't strictly fixing an error, it might sit until the next time that we're
 working on a large revision: expect on the order of months or years. Thank you

diff --git a/README.md b/README.md
@@ -35,12 +35,11 @@ $ cargo install mdbook --locked --version <version_num>
 
 The book also uses two mdbook plugins which are part of this repository. If you
 do not install them, you will see warnings when building and the output will not
-look right, but you *will* still be able to build the book. To use the plugins,
+look right, but you _will_ still be able to build the book. To use the plugins,
 you should run:
 
 ```bash
-$ cargo install --locked --path packages/mdbook-trpl-listing
-$ cargo install --locked --path packages/mdbook-trpl-note
+$ cargo install --locked --path packages/mdbook-trpl
 ```
 
 ## Building
@@ -55,6 +54,7 @@ The output will be in the `book` subdirectory. To check it out, open it in
 your web browser.
 
 _Firefox:_
+
 ```bash
 $ firefox book/index.html                       # Linux
 $ open -a "Firefox" book/index.html             # OS X
@@ -63,6 +63,7 @@ $ start firefox.exe .\book\index.html           # Windows (Cmd)
 ```
 
 _Chrome:_
+
 ```bash
 $ google-chrome book/index.html                 # Linux
 $ open -a "Google Chrome" book/index.html       # OS X
@@ -89,8 +90,7 @@ to keep the online version of the book close to the print version when
 possible, it may take longer than you're used to for us to address your issue
 or pull request.
 
-So far, we've been doing a larger revision to coincide with [Rust
-Editions](https://doc.rust-lang.org/edition-guide/). Between those larger
+So far, we've been doing a larger revision to coincide with [Rust Editions](https://doc.rust-lang.org/edition-guide/). Between those larger
 revisions, we will only be correcting errors. If your issue or pull request
 isn't strictly fixing an error, it might sit until the next time that we're
 working on a large revision: expect on the order of months or years. Thank you

diff --git a/ci/dictionary.txt b/ci/dictionary.txt
@@ -164,6 +164,7 @@ Enums
 eprintln
 Erlang
 ErrorKind
+Español
 eval
 executables
 ExitCode
@@ -392,6 +393,7 @@ PendingReviewPost
 PlaceholderType
 polymorphism
 PoolCreationError
+por
 portia
 postfix
 powershell
@@ -458,6 +460,7 @@ RUSTFLAGS
 Rustonomicon
 rustfix
 rustfmt
+RustLangES
 rustup
 sampleproject
 screenshot

diff --git a/dprint.jsonc b/dprint.jsonc
@@ -0,0 +1,33 @@
+{
+  "typescript": {
+  },
+  "json": {
+  },
+  "markdown": {
+  },
+  "malva": {
+  },
+  "excludes": [
+    "**/node_modules",
+    "**/*-lock.json",
+    "**/target",
+    // We don’t to apply auto-formatting to this *yet*, at a minimum. It may be
+    // helpful as a way of replacing some of the manual formatting we do in both
+    // the nostarch script and the script for pulling data back over from docx,
+    // though, so we may *start* doing so in the future.
+    "nostarch",
+    // These should never change at this point
+    "2018-edition",
+    "first-edition",
+    "second-edition",
+    "redirects",
+    // has empty list items which look like headings to a formatter
+    ".github/ISSUE_TEMPLATE/bug_report.md",
+  ],
+  "plugins": [
+    "https://plugins.dprint.dev/typescript-0.93.3.wasm",
+    "https://plugins.dprint.dev/json-0.19.4.wasm",
+    "https://plugins.dprint.dev/markdown-0.17.8.wasm",
+    "https://plugins.dprint.dev/g-plane/malva-v0.11.0.wasm",
+  ],
+}
diff --git a/ferris.js b/ferris.js
@@ -7,50 +7,50 @@
 /** @type {Array<FerrisType>} */
 const FERRIS_TYPES = [
   {
-    attr: 'does_not_compile',
-    title: 'This code does not compile!'
+    attr: "does_not_compile",
+    title: "This code does not compile!",
   },
   {
-    attr: 'panics',
-    title: 'This code panics!'
+    attr: "panics",
+    title: "This code panics!",
   },
   {
-    attr: 'not_desired_behavior',
-    title: 'This code does not produce the desired behavior.'
-  }
-]
+    attr: "not_desired_behavior",
+    title: "This code does not produce the desired behavior.",
+  },
+];
 
-document.addEventListener('DOMContentLoaded', () => {
+document.addEventListener("DOMContentLoaded", () => {
   for (let ferrisType of FERRIS_TYPES) {
-    attachFerrises(ferrisType)
+    attachFerrises(ferrisType);
   }
-})
+});
 
 /**
  * @param {FerrisType} type
  */
 function attachFerrises(type) {
-  let elements = document.getElementsByClassName(type.attr)
+  let elements = document.getElementsByClassName(type.attr);
 
   for (let codeBlock of elements) {
     // Skip SVG etc.: in principle, these should never be attached to those, but
     // this means if someone happens to have a browser extension which *is*
     // attaching them, it will not break the code.
     if (!(codeBlock instanceof HTMLElement)) {
-      continue
+      continue;
     }
 
-    let lines = codeBlock.innerText.replace(/\n$/, '').split(/\n/).length
+    let lines = codeBlock.innerText.replace(/\n$/, "").split(/\n/).length;
 
     /** @type {'small' | 'large'} */
-    let size = lines < 4 ? 'small' : 'large'
+    let size = lines < 4 ? "small" : "large";
 
-    let container = prepareFerrisContainer(codeBlock, size == 'small')
+    let container = prepareFerrisContainer(codeBlock, size == "small");
     if (!container) {
-      continue
+      continue;
     }
 
-    container.appendChild(createFerris(type, size))
+    container.appendChild(createFerris(type, size));
   }
 }
 
@@ -60,22 +60,22 @@ function attachFerrises(type) {
  * @returns {Element | null} - The container element to use.
  */
 function prepareFerrisContainer(element, useButtons) {
-  let foundButtons = element.parentElement?.querySelector('.buttons')
+  let foundButtons = element.parentElement?.querySelector(".buttons");
   if (useButtons && foundButtons) {
-    return foundButtons
+    return foundButtons;
   }
 
-  let div = document.createElement('div')
-  div.classList.add('ferris-container')
+  let div = document.createElement("div");
+  div.classList.add("ferris-container");
 
   if (!element.parentElement) {
     console.error(`Could not install Ferris on ${element}, which is missing a parent`);
     return null;
   }
 
-  element.parentElement.insertBefore(div, element)
+  element.parentElement.insertBefore(div, element);
 
-  return div
+  return div;
 }
 
 /**
@@ -84,17 +84,17 @@ function prepareFerrisContainer(element, useButtons) {
  * @returns {HTMLAnchorElement} - The generated anchor element.
  */
 function createFerris(type, size) {
-  let a = document.createElement('a')
-  a.setAttribute('href', 'ch00-00-introduction.html#ferris')
-  a.setAttribute('target', '_blank')
+  let a = document.createElement("a");
+  a.setAttribute("href", "ch00-00-introduction.html#ferris");
+  a.setAttribute("target", "_blank");
 
-  let img = document.createElement('img')
-  img.setAttribute('src', 'img/ferris/' + type.attr + '.svg')
-  img.setAttribute('title', type.title)
-  img.classList.add('ferris')
-  img.classList.add('ferris-' + size)
+  let img = document.createElement("img");
+  img.setAttribute("src", "img/ferris/" + type.attr + ".svg");
+  img.setAttribute("title", type.title);
+  img.classList.add("ferris");
+  img.classList.add("ferris-" + size);
 
-  a.appendChild(img)
+  a.appendChild(img);
 
-  return a
+  return a;
 }
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Ran dprint fmt on the repo
		3a30e4c1fbe641afc066b3af9eb01dcdf5ed8b24
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,3 +6,5 @@ target @@
     tmp
     .nova
+    .vscode
+    .zed