Merging upstream version 1.75.0+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

16 files changed, 81 insertions, 45 deletions

diff --git a/src/doc/rust-by-example/src/SUMMARY.md b/src/doc/rust-by-example/src/SUMMARY.md
index b1bcf223d..b8e6ada91 100644
--- a/src/doc/rust-by-example/src/SUMMARY.md
+++ b/src/doc/rust-by-example/src/SUMMARY.md
@@ -161,7 +161,7 @@
         - [Unpacking options with `?`](error/option_unwrap/question_mark.md)
         - [Combinators: `map`](error/option_unwrap/map.md)
         - [Combinators: `and_then`](error/option_unwrap/and_then.md)
-        - [Defaults: `or`, `or_else`, `get_or_insert`, 'get_or_insert_with`](error/option_unwrap/defaults.md)
+        - [Defaults: `or`, `or_else`, `get_or_insert`, `get_or_insert_with`](error/option_unwrap/defaults.md)
     - [`Result`](error/result.md)
         - [`map` for `Result`](error/result/result_map.md)
         - [aliases for `Result`](error/result/result_alias.md)
@@ -197,7 +197,7 @@
     - [File I/O](std_misc/file.md)
         - [`open`](std_misc/file/open.md)
         - [`create`](std_misc/file/create.md)
-        - [`read lines`](std_misc/file/read_lines.md)
+        - [`read_lines`](std_misc/file/read_lines.md)
     - [Child processes](std_misc/process.md)
         - [Pipes](std_misc/process/pipe.md)
         - [Wait](std_misc/process/wait.md)
diff --git a/src/doc/rust-by-example/src/attribute.md b/src/doc/rust-by-example/src/attribute.md
index dcb7d6c1a..d6a49dc01 100644
--- a/src/doc/rust-by-example/src/attribute.md
+++ b/src/doc/rust-by-example/src/attribute.md
@@ -14,9 +14,34 @@ can be used to/for:
 * mark functions that will be part of a benchmark
 * [attribute like macros][macros]
 
-When attributes apply to a whole crate, their syntax is `#![crate_attribute]`,
-and when they apply to a module or item, the syntax is `#[item_attribute]`
-(notice the missing bang `!`).
+Attributes look like `#[outer_attribute]` or `#![inner_attribute]`,
+with the difference between them being where they apply.
+
+- `#[outer_attribute]` applies to the [item][item] immediately
+  following it. Some examples of items are: a function, a module
+  declaration, a constant, a structure, an enum. Here is an example
+  where attribute `#[derive(Debug)]` applies to the struct
+  `Rectangle`:
+  ```rust
+  #[derive(Debug)]
+  struct Rectangle {
+      width: u32,
+      height: u32,
+  }
+  ```
+
+- `#![inner_attribute]` applies to the enclosing [item][item] (typically a
+  module or a crate). In other words, this attribute is intepreted as
+  applying to the entire scope in which it's place. Here is an example
+  where `#![allow(unusude_variables)]` applies to the whole crate (if
+  placed in `main.rs`):
+  ```rust
+  #![allow(unused_variables)]
+
+  fn main() {
+      let x = 3; // This would normally warn about an unused variable.
+  }
+  ```
 
 Attributes can take arguments with different syntaxes:
 
@@ -36,5 +61,6 @@ Attributes can have multiple values and can be separated over multiple lines, to
 
 [cfg]: attribute/cfg.md
 [crate]: attribute/crate.md
+[item]: https://doc.rust-lang.org/stable/reference/items.html
 [lint]: https://en.wikipedia.org/wiki/Lint_%28software%29
 [macros]: https://doc.rust-lang.org/book/ch19-06-macros.html#attribute-like-macros
diff --git a/src/doc/rust-by-example/src/custom_types/constants.md b/src/doc/rust-by-example/src/custom_types/constants.md
index 8878ba834..c060db734 100644
--- a/src/doc/rust-by-example/src/custom_types/constants.md
+++ b/src/doc/rust-by-example/src/custom_types/constants.md
@@ -4,7 +4,7 @@ Rust has two different types of constants which can be declared in any scope
 including global. Both require explicit type annotation:
 
 * `const`: An unchangeable value (the common case).
-* `static`: A possibly `mut`able variable with [`'static`][static] lifetime.
+* `static`: A possibly mutable variable with [`'static`][static] lifetime.
   The static lifetime is inferred and does not have to be specified.
   Accessing or modifying a mutable static variable is [`unsafe`][unsafe].
 
diff --git a/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md b/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md
index 831625229..04de93cc7 100644
--- a/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md
+++ b/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md
@@ -8,7 +8,8 @@ function is being executed and return `None`.
 ```rust,editable
 fn next_birthday(current_age: Option<u8>) -> Option<String> {
 	// If `current_age` is `None`, this returns `None`.
-	// If `current_age` is `Some`, the inner `u8` gets assigned to `next_age`
+	// If `current_age` is `Some`, the inner `u8` value + 1
+    // gets assigned to `next_age`
     let next_age: u8 = current_age? + 1;
     Some(format!("Next year I will be {}", next_age))
 }
diff --git a/src/doc/rust-by-example/src/flow_control/while_let.md b/src/doc/rust-by-example/src/flow_control/while_let.md
index 897375a8e..745b7ae75 100644
--- a/src/doc/rust-by-example/src/flow_control/while_let.md
+++ b/src/doc/rust-by-example/src/flow_control/while_let.md
@@ -31,26 +31,24 @@ loop {
 Using `while let` makes this sequence much nicer:
 
 ```rust,editable
-fn main() {
-    // Make `optional` of type `Option<i32>`
-    let mut optional = Some(0);
-
-    // This reads: "while `let` destructures `optional` into
-    // `Some(i)`, evaluate the block (`{}`). Else `break`.
-    while let Some(i) = optional {
-        if i > 9 {
-            println!("Greater than 9, quit!");
-            optional = None;
-        } else {
-            println!("`i` is `{:?}`. Try again.", i);
-            optional = Some(i + 1);
-        }
-        // ^ Less rightward drift and doesn't require
-        // explicitly handling the failing case.
+// Make `optional` of type `Option<i32>`
+let mut optional = Some(0);
+
+// This reads: "while `let` destructures `optional` into
+// `Some(i)`, evaluate the block (`{}`). Else `break`.
+while let Some(i) = optional {
+    if i > 9 {
+        println!("Greater than 9, quit!");
+        optional = None;
+    } else {
+        println!("`i` is `{:?}`. Try again.", i);
+        optional = Some(i + 1);
     }
-    // ^ `if let` had additional optional `else`/`else if`
-    // clauses. `while let` does not have these.
+    // ^ Less rightward drift and doesn't require
+    // explicitly handling the failing case.
 }
+// ^ `if let` had additional optional `else`/`else if`
+// clauses. `while let` does not have these.
 ```
 
 ### See also:
diff --git a/src/doc/rust-by-example/src/fn/closures.md b/src/doc/rust-by-example/src/fn/closures.md
index 82286003b..e7b8c9867 100644
--- a/src/doc/rust-by-example/src/fn/closures.md
+++ b/src/doc/rust-by-example/src/fn/closures.md
@@ -14,7 +14,7 @@ variable names *must* be specified.
 
 Other characteristics of closures include:
 * using `||` instead of `()` around input variables.
-* optional body delimination (`{}`) for a single expression (mandatory otherwise).
+* optional body delimitation (`{}`) for a single expression (mandatory otherwise).
 * the ability to capture the outer environment variables.
 
 ```rust,editable
@@ -26,7 +26,7 @@ fn main() {
     // TODO: uncomment the line above and see the compiler error. The compiler
     // suggests that we define a closure instead.
 
-    // Closures are anonymous, here we are binding them to references
+    // Closures are anonymous, here we are binding them to references.
     // Annotation is identical to function annotation but is optional
     // as are the `{}` wrapping the body. These nameless functions
     // are assigned to appropriately named variables.
diff --git a/src/doc/rust-by-example/src/fn/hof.md b/src/doc/rust-by-example/src/fn/hof.md
index 88918cb52..9be5b41fe 100644
--- a/src/doc/rust-by-example/src/fn/hof.md
+++ b/src/doc/rust-by-example/src/fn/hof.md
@@ -10,7 +10,7 @@ fn is_odd(n: u32) -> bool {
 }
 
 fn main() {
-    println!("Find the sum of all the squared odd numbers under 1000");
+    println!("Find the sum of all the numbers with odd squares under 1000");
     let upper = 1000;
 
     // Imperative approach
diff --git a/src/doc/rust-by-example/src/meta/doc.md b/src/doc/rust-by-example/src/meta/doc.md
index e9e51186f..b1732f837 100644
--- a/src/doc/rust-by-example/src/meta/doc.md
+++ b/src/doc/rust-by-example/src/meta/doc.md
@@ -2,7 +2,8 @@
 
 Use `cargo doc` to build documentation in `target/doc`.
 
-Use `cargo test` to run all tests (including documentation tests), and `cargo test --doc` to only run documentation tests.
+Use `cargo test` to run all tests (including documentation tests), and `cargo
+test --doc` to only run documentation tests.
 
 These commands will appropriately invoke `rustdoc` (and `rustc`) as required.
 
@@ -67,7 +68,8 @@ $ rustdoc --test --extern doc="libdoc.rlib" doc.rs
 
 ## Doc attributes
 
-Below are a few examples of the most common `#[doc]` attributes used with `rustdoc`.
+Below are a few examples of the most common `#[doc]` attributes used with
+`rustdoc`.
 
 ### `inline`
 
@@ -104,7 +106,8 @@ Using this tells `rustdoc` not to include this in documentation:
 pub use self::async_await::*;
 ```
 
-For documentation, `rustdoc` is widely used by the community. It's what is used to generate the [std library docs](https://doc.rust-lang.org/std/).
+For documentation, `rustdoc` is widely used by the community. It's what is used
+to generate the [std library docs](https://doc.rust-lang.org/std/).
 
 ### See also:
 
diff --git a/src/doc/rust-by-example/src/meta/playground.md b/src/doc/rust-by-example/src/meta/playground.md
index 7fcfad1a7..e78552d29 100644
--- a/src/doc/rust-by-example/src/meta/playground.md
+++ b/src/doc/rust-by-example/src/meta/playground.md
@@ -1,6 +1,7 @@
 # Playground
 
-The [Rust Playground](https://play.rust-lang.org/) is a way to experiment with Rust code through a web interface.
+The [Rust Playground](https://play.rust-lang.org/) is a way to experiment with
+Rust code through a web interface.
 
 ## Using it with `mdbook`
 
@@ -12,7 +13,9 @@ fn main() {
 }
 ```
 
-This allows the reader to both run your code sample, but also modify and tweak it. The key here is the adding the word `editable` to your codefence block separated by a comma.
+This allows the reader to both run your code sample, but also modify and tweak
+it. The key here is the adding the word `editable` to your codefence block
+separated by a comma.
 
 ````markdown
 ```rust,editable
@@ -20,7 +23,8 @@ This allows the reader to both run your code sample, but also modify and tweak i
 ```
 ````
 
-Additionally, you can add `ignore` if you want `mdbook` to skip your code when it builds and tests.
+Additionally, you can add `ignore` if you want `mdbook` to skip your code when
+it builds and tests.
 
 ````markdown
 ```rust,editable,ignore
@@ -30,7 +34,10 @@ Additionally, you can add `ignore` if you want `mdbook` to skip your code when i
 
 ## Using it with docs
 
-You may have noticed in some of the [official Rust docs][official-rust-docs] a button that says "Run", which opens the code sample up in a new tab in Rust Playground. This feature is enabled if you use the #[doc] attribute called [`html_playground_url`][html-playground-url].
+You may have noticed in some of the [official Rust docs][official-rust-docs] a
+button that says "Run", which opens the code sample up in a new tab in Rust
+Playground. This feature is enabled if you use the `#[doc]` attribute called
+[`html_playground_url`][html-playground-url].
 
 ### See also:
 
diff --git a/src/doc/rust-by-example/src/primitives/array.md b/src/doc/rust-by-example/src/primitives/array.md
index 5f5e69944..704a2131c 100644
--- a/src/doc/rust-by-example/src/primitives/array.md
+++ b/src/doc/rust-by-example/src/primitives/array.md
@@ -6,7 +6,7 @@ at compile time, is part of their type signature `[T; length]`.
 
 Slices are similar to arrays, but their length is not known at compile time.
 Instead, a slice is a two-word object; the first word is a pointer to the data,
-the second word the length of the slice. The word size is the same as usize,
+the second word is the length of the slice. The word size is the same as usize,
 determined by the processor architecture, e.g. 64 bits on an x86-64. Slices can
 be used to borrow a section of an array and have the type signature `&[T]`.
 
diff --git a/src/doc/rust-by-example/src/scope/lifetime.md b/src/doc/rust-by-example/src/scope/lifetime.md
index 68b42d380..01c4bf405 100644
--- a/src/doc/rust-by-example/src/scope/lifetime.md
+++ b/src/doc/rust-by-example/src/scope/lifetime.md
@@ -1,6 +1,6 @@
 # Lifetimes
 
-A *lifetime* is a construct of the compiler (or more specifically, its *borrow
+A *lifetime* is a construct the compiler (or more specifically, its *borrow
 checker*) uses to ensure all borrows are valid. Specifically, a variable's
 lifetime begins when it is created and ends when it is destroyed. While
 lifetimes and scopes are often referred to together, they are not the same.
diff --git a/src/doc/rust-by-example/src/scope/move.md b/src/doc/rust-by-example/src/scope/move.md
index 0433e8ac1..df631ee08 100644
--- a/src/doc/rust-by-example/src/scope/move.md
+++ b/src/doc/rust-by-example/src/scope/move.md
@@ -1,7 +1,7 @@
 # Ownership and moves
 
 Because variables are in charge of freeing their own resources, 
-**resources can only have one owner**. This also prevents resources 
+**resources can only have one owner**. This prevents resources 
 from being freed more than once. Note that not all variables own 
 resources (e.g. [references]).
 
diff --git a/src/doc/rust-by-example/src/std/hash/alt_key_types.md b/src/doc/rust-by-example/src/std/hash/alt_key_types.md
index ab94819b2..7e68e8c67 100644
--- a/src/doc/rust-by-example/src/std/hash/alt_key_types.md
+++ b/src/doc/rust-by-example/src/std/hash/alt_key_types.md
@@ -3,7 +3,7 @@
 Any type that implements the `Eq` and `Hash` traits can be a key in `HashMap`. 
 This includes:
 
-* `bool` (though not very useful since there is only two possible keys)
+* `bool` (though not very useful since there are only two possible keys)
 * `int`, `uint`, and all variations thereof
 * `String` and `&str` (protip: you can have a `HashMap` keyed by `String`
 and call `.get()` with an `&str`)
diff --git a/src/doc/rust-by-example/src/std_misc/arg/matching.md b/src/doc/rust-by-example/src/std_misc/arg/matching.md
index 4cb68eabf..4a96fbc21 100644
--- a/src/doc/rust-by-example/src/std_misc/arg/matching.md
+++ b/src/doc/rust-by-example/src/std_misc/arg/matching.md
@@ -70,6 +70,9 @@ fn main() {
 }
 ```
 
+If you named your program `match_args.rs` and compile it like this `rustc
+match_args.rs`, you can execute it as follows:
+
 ```shell
 $ ./match_args Rust
 This is not the answer.
diff --git a/src/doc/rust-by-example/src/std_misc/file/read_lines.md b/src/doc/rust-by-example/src/std_misc/file/read_lines.md
index 216b0181c..1a2a64241 100644
--- a/src/doc/rust-by-example/src/std_misc/file/read_lines.md
+++ b/src/doc/rust-by-example/src/std_misc/file/read_lines.md
@@ -56,15 +56,13 @@ fn main() {
     // File hosts.txt must exist in the current path
     if let Ok(lines) = read_lines("./hosts.txt") {
         // Consumes the iterator, returns an (Optional) String
-        for line in lines {
-            if let Ok(ip) = line {
-                println!("{}", ip);
-            }
+        for line in lines.flatten() {
+            println!("{}", line);
         }
     }
 }
 
-// The output is wrapped in a Result to allow matching on errors
+// The output is wrapped in a Result to allow matching on errors.
 // Returns an Iterator to the Reader of the lines of the file.
 fn read_lines<P>(filename: P) -> io::Result<io::Lines<io::BufReader<File>>>
 where P: AsRef<Path>, {
diff --git a/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md b/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md
index ee25b1661..9cc162f51 100644
--- a/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md
+++ b/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md
@@ -30,7 +30,7 @@ use std::thread;
 fn main() {
 
     // This is our data to process.
-    // We will calculate the sum of all digits via a threaded  map-reduce algorithm.
+    // We will calculate the sum of all digits via a threaded map-reduce algorithm.
     // Each whitespace separated chunk will be handled in a different thread.
     //
     // TODO: see what happens to the output if you insert spaces!