Proofreading fixes

src/installation/index.md

@@ -22,12 +22,12 @@ Please note that you can host the development environment in a [container][use-c
 
 Make sure you have [Rust][rust-lang-org] installed. If not, see the instructions on the [rustup][rustup.rs-website] website.
 
+> **Warning**: When using Unix based systems, installing Rust via a system package manager (e.g. `brew`, `apt`, `dnf`, etc.) can result in various issues and incompatibilities, so it's best to use [rustup][rustup.rs-website] instead.
+
 When using Windows, make sure you have installed one of the ABIs listed below. For more details, see the [Windows][rustup-book-windows] chapter in The rustup book.
 - **MSVC**: Recommended ABI, included in the list of `rustup` default requirements. Use it for interoperability with the software produced by Visual Studio.
 - **GNU**: ABI used by the GCC toolchain. Install it yourself for interoperability with the software built with the MinGW/MSYS2 toolchain.
 
-> **Warning**: When using Unix based systems, installing Rust via a system package manager (e.g. `brew`, `apt`, `dnf`, etc.) can result in various issues and incompatibilities, so it's best to use [rustup][rustup.rs-website] instead.
-
 See also [alternative installation methods][rust-alt-installation].
 
 [rustup.rs-website]: https://rustup.rs/
@@ -61,23 +61,21 @@ To build Rust applications for the Espressif chips based on `RISC-V` architectur
 
     - For `std` applications:
 
-      Since this target is currently [Tier 3][rust-lang-book--platform-support-tier3], it does not have pre-built objects distributed through `rustup` and, unlike the `no_std` target, **nothing needs to be installed**. Refer to the [*-esp-idf][rust-lang-book--platform-support--esp-idf] section of the rustc book for the correct target for your device. 
-      
-      - `riscv32imc-esp-espidf` for MCUs which do not support atomics, like ESP32-C2 and ESP32-C3
-      - `riscv32imac-esp-espidf` for MCUs which support atomics, like ESP32-C6, ESP32-H2, and ESP32-P4
+      Since this target is currently [Tier 3][rust-lang-book--platform-support-tier3], it does not have pre-built objects distributed through `rustup` and, unlike the `no_std` target, **nothing needs to be installed**. Refer to the [*-esp-idf][rust-lang-book--platform-support--esp-idf] section of the rustc book for the correct target for your device.
+
+      - `riscv32imc-esp-espidf` for SoCs which do not support atomics, like ESP32-C2 and ESP32-C3
+      - `riscv32imac-esp-espidf` for SoCs which support atomics, like ESP32-C6, ESP32-H2, and ESP32-P4
 
 [rust-lang-book--platform-support-tier2]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-2
 [wiki-riscv-standard-extensions]: https://en.wikichip.org/wiki/risc-v/standard_extensions
 [rust-lang-book--platform-support-tier3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3
 [rust-lang-book--platform-support--esp-idf]: https://doc.rust-lang.org/nightly/rustc/platform-support/esp-idf.html
 
-
 3. To build `std` projects, you also need to install:
     - [`LLVM`][llvm-website] compiler infrastructure
     - Other [`std` development requirements][rust-esp-book-std-requirements]
     - In your project's file `.cargo/config.toml`, add the unstable Cargo [feature][cargo-book-unstable-features] `-Z build-std`. Our [template projects][rust-esp-book-write-app-generate-project] that are discussed later in this book already include this.
 
-
 [llvm-website]: https://llvm.org/
 [rust-esp-book-std-requirements]: #std-development-requirements
 [cargo-book-unstable-features]: https://doc.rust-lang.org/cargo/reference/unstable.html
@@ -152,12 +150,12 @@ The forked compiler can coexist with the standard Rust compiler, allowing both t
 > 1. Changes in `LLVM` fork. Already in progress, see the status in this [tracking issue][llvm-github-fork-upstream issue].
 > 2. Rust compiler forks. If `LLVM` changes are accepted, we will proceed with the Rust compiler changes.
 
-
 [llvm-github-fork]: https://github.com/espressif/llvm-project
 [gcc-toolchain-github-fork]: https://github.com/espressif/crosstool-NG/
 [rustup-overrides]: https://rust-lang.github.io/rustup/overrides.html
 [llvm-github-fork-upstream issue]: https://github.com/espressif/llvm-project/issues/4
 
+If you run into an error, please, check the [Troubleshooting][troubleshooting] chapter.
 
 ### Other installation methods for Xtensa targets
 
@@ -181,7 +179,7 @@ Regardless of the target architecture, make sure you have the following required
 
 The std runtime uses [ESP-IDF][esp-idf-github] (Espressif IoT Development Framework) as hosted environment but, users do not need to install it. ESP-IDF is automatically downloaded and installed by [esp-idf-sys][esp-idf-sys-github], a crate that all std projects need to use, when building a std application.
 
-
+[troubleshooting]: ../misc/troubleshooting.md
 [rust-esp-book-overview-std]: ../overview/using-the-standard-library.md
 [python-website-download]: https://www.python.org/downloads/
 [git-website-download]: https://git-scm.com/downloads
@@ -201,14 +199,13 @@ For each Rust release, we generate the tag with the following naming convention:
 - `<chip>_<rust-toolchain-version>`
   - For example, `esp32_1.64.0.0` contains the ecosystem for developing `std`, and `no_std` applications for `ESP32` with the `1.64.0.0` Xtensa Rust toolchain.
 
-There are special cases
+There are special cases:
 
 - `<chip>` can be `all` which indicates compatibility with all Espressif targets
 - `<rust-toolchain-version>` can be `latest` which indicates the latest release of the `Xtensa` Rust toolchain
 
 Depending on your operating system, you can choose any container runtime, such as [Docker], [Podman], or [Lima].
 
-
 [Docker]: https://www.docker.com/
 [Podman]: https://podman.io/
 [Lima]: https://github.com/lima-vm/lima

src/introduction.md

@@ -10,25 +10,12 @@ For tools and libraries relating to Rust on ESP, please see the [esp-rs organiza
 [Espressif]: https://espressif.com/
 [esp-rs organization]: https://github.com/esp-rs/
 
-> **A Note on Device Support**
->
-> The contents of this book apply to the ESP32 series of devices only; this
-> includes:
->
-> - ESP32 Series
-> - ESP32 C-Series
-> - ESP32 S-Series
-> - ESP32 H-Series
->
-> The ESP8266 series is outside the scope of this book. Rust support for the
-> ESP8266 series is limited and is not being officially supported by Espressif.
-
 ## Who This Book is For
 
-This book is intended for people with some experience with Rust, and also assumes rudimentary knowledge of embedded development and electronics. For those without prior experience, we recommend first reading the [Assumptions and Prerequisites] and [Other Resources] sections to get up to speed.
+This book is intended for people with some experience with Rust, and also assumes rudimentary knowledge of embedded development and electronics. For those without prior experience, we recommend first reading the [Assumptions and Prerequisites] and [Resources] sections to get up to speed.
 
 [assumptions and prerequisites]: #assumptions-and-prerequisites
-[other resources]: #other-resources
+[resources]: #resources
 
 ### Assumptions and Prerequisites
 
@@ -42,7 +29,7 @@ This book is intended for people with some experience with Rust, and also assume
 
 [2021 edition]: https://doc.rust-lang.org/edition-guide/rust-2021/index.html
 
-### Other Resources
+### Resources
 
 If you are unfamiliar or less experienced with anything mentioned above, or if you would just like more information about a particular topic mentioned in this book, you may find these resources helpful.
 
@@ -59,7 +46,7 @@ If you are unfamiliar or less experienced with anything mentioned above, or if y
 [embedded rust on espressif]: https://esp-rs.github.io/std-training/
 [ferrous systems]: https://ferrous-systems.com/
 
-### Translations
+## Translations
 
 This book is currently available in English only. Once the contents of the book stabilize somewhat, we plan on translating the book into additional languages. As translations become available, this section will be updated to include them.
 

src/overview/bare-metal.md

@@ -2,20 +2,17 @@
 
 Using `no_std` may be more familiar to embedded Rust developers; it does not use `std` (the Rust [`standard`][rust-lib-std] library) but instead uses a subset, the [`core`][rust-lib-core] library. [The Embedded Rust Book][embedded-rust-book] has a great [section][embedded-rust-book-no-std] on this.
 
-It's important to note that since `no_std` uses the Rust `core` library, a subset of the Rust `standard` library,  a `no_std` crate can compile in `std` environment but the opposite is not true. Therefore, when creating crates it's worth keeping in mind if it needs the `standard` library to function.
-
+It is important to note that `no_std` uses the Rust `core` library. As this library is part of the Rust `standard` library, a `no_std` crate can compile in `std` environment. However, the opposite is not true: an `std` crate cannot compile in `no_std` environment.  This information is worth remembering when deciding which library to choose.
 
 [embedded-rust-book]: https://docs.rust-embedded.org/
 [embedded-rust-book-no-std]: https://docs.rust-embedded.org/book/intro/no-std.html
 [rust-lib-core]: https://doc.rust-lang.org/core/index.html
 [rust-lib-std]: https://doc.rust-lang.org/std/index.html
 
-
 ## Current support
 
 The table below covers the current support for `no_std` at this moment for different Espressif products.
 
-
 |          | [HAL][esp-rs/esp-hal] | [Wi-Fi/BLE/ESP-NOW][esp-rs/esp-wifi] | [Backtrace][esp-rs/esp-backtrace] | [Storage][esp-rs/esp-storage] |
 | -------- | :-------------------: | :----------------------------------: | :-------------------------------: | :---------------------------: |
 | ESP32    |           ✅           |                  ✅                   |                 ✅                 |               ✅               |
@@ -32,6 +29,7 @@ The table below covers the current support for `no_std` at this moment for diffe
 > - [ESP8266 HAL][esp-rs/esp8266-hal] is in maintenance mode and no further development will be done for this chip.
 
 [esp-wifi-current-support]: https://github.com/esp-rs/esp-wifi#current-support
+
 ### Relevant `esp-rs` crates
 
 | Repository             | Description                                                |

src/overview/index.md

@@ -8,7 +8,7 @@ There are the following approaches to using Rust on Espressif chips:
 Both approaches have their advantages and disadvantages, so you should make a decision based on your project's needs. This chapter contains an overview of the two approaches:
 
 - [Using the Standard Library (`std`)][rust-esp-book-std]
-- [Developing on Bare Metal (`no_std`)][rust-esp-book-no-std]
+- [Using the Core Library (`no_std`)][rust-esp-book-no-std]
 
 [rust-esp-book-std]: ./using-the-standard-library.md
 [rust-esp-book-no-std]: ./bare-metal.md
@@ -19,17 +19,13 @@ See also the comparison of the different runtimes in [The Embedded Rust Book][em
 
 The [esp-rs organization] on GitHub is home to a number of repositories related to running Rust on Espressif chips. Most of the required crates have their source code hosted here.
 
-> A note on the repository naming convention
->
-> In the [esp-rs organization] we use the following wording:
->
-> - Repositories starting with `esp-idf-` are focused on `std` approach. E.g. `esp-idf-hal`
-> - Repositories starting with `esp-` are focused on `no_std` approach. E.g. `esp-hal`
->
-> It is easy to remember as follows:
->
-> - `no_std` works on top of bare metal, so `esp-` is an Espressif chip
->- `std`, apart from bare metal, also needs an [additional layer](https://github.com/espressif/esp-idf), which is `esp-idf-`
+## Repository naming convention
+
+In the [esp-rs organization] we use the following wording:
+- Repositories starting with `esp-` are focused on `no_std` approach. E.g. `esp-hal`
+  - `no_std` works on top of bare metal, so `esp-` is an Espressif chip
+- Repositories starting with `esp-idf-` are focused on `std` approach. E.g. `esp-idf-hal`
+  - `std`, apart from bare metal, also needs an [additional layer](https://github.com/espressif/esp-idf), which is `esp-idf-`
 
 [esp-rs organization]: https://github.com/esp-rs/
 
@@ -52,8 +48,7 @@ The [esp-rs organization] on GitHub is home to a number of repositories related
 | ESP32-H2 |   ✅   |    ✅     |
 | ESP8266  |   ❌   |    ✅     |
 
-The products supported in certain circumstances will be called _supported Espressif products_ throughout the book.
-
-As of now, the Espressif products supported by the esp-idf framework are the ones supported for Rust `std` development. For details on different versions of esp-idf and support of Espressif chips, see [this table][esp-idf-release-compatibility].
+> **Note**: The ESP8266 series is outside the scope of this book. Rust support for the
+> ESP8266 series is limited and is not being officially supported by Espressif.
 
-[esp-idf-release-compatibility]: https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility
+The products supported in certain circumstances will be called _supported Espressif products_ throughout the book.

src/overview/using-the-standard-library.md

@@ -1,8 +1,6 @@
 # Using the Standard Library (`std`)
 
-Espressif provides a C-based development framework called [esp-idf][esp-idf-github] which has, or will have, support for all Espressif chips starting with the ESP32; note that this framework does _not_ support the ESP8266. See also [Support for Espressif Products][rust-esp-book-overview-index].
-
-[rust-esp-book-overview-index]: index.md#support-for-espressif-products
+Espressif provides a C-based development framework called [esp-idf][esp-idf-github] which has, or will have, support for all Espressif chips starting with the ESP32; note that this framework does _not_ support the ESP8266.
 
 `esp-idf`, in turn, provides a [newlib][newlib-env] environment with enough functionality to build the Rust standard library (`std`) on top of it. This is the approach that is being taken to enable `std` support on ESP devices.
 
@@ -11,7 +9,7 @@ Espressif provides a C-based development framework called [esp-idf][esp-idf-gith
 
 ## Current Support
 
-As of now, the Espressif products supported by the [esp-idf framework][esp-idf-release-compatibility] are the ones supported for Rust `std` development.
+The Espressif products supported by the esp-idf framework are the ones supported for Rust `std` development. For details on different versions of esp-idf and support of Espressif chips, see [this table][esp-idf-release-compatibility].
 
 [esp-idf-release-compatibility]: https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility/
 

src/tooling/debugging/vscode-debugging.md

@@ -4,9 +4,9 @@ There is also a possibility to debug with graphical output directly in Visual St
 
 ## ESP32
 
-### Hardware Setup
+### Configuration
 
-ESP32 doesn't have a built-in JTAG interface, so you have to connect an external JTAG adapter to the ESP32 board, for example, [ESP-Prog](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html) can be used.
+1. Connect an external JTAG adapter: [ESP-Prog](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html) can be used.
 
 |  ESP32 Pin  | JTAG Signal |
 | :---------: | :---------: |
@@ -19,11 +19,10 @@ ESP32 doesn't have a built-in JTAG interface, so you have to connect an external
 
 **Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB.
 
-## Set up VSCode
-
-1. Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) extension for VScode.
-2. Create the `.vscode/launch.json` file in the project tree you want to debug. [This](https://github.com/esp-rs/esp32-hal/blob/master/.vscode/launch.json) can be used as a template file.
-3. Update **executable**, **svdFile**, **serverpath** paths, and **toolchainPrefix** field.
+2. Set up VSCode
+   1. Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) extension for VScode.
+   2. Create the `.vscode/launch.json` file in the project tree you want to debug. [This](https://github.com/esp-rs/esp32-hal/blob/master/.vscode/launch.json) can be used as a template file.
+   3. Update `executable`, `svdFile`, `serverpath` paths, and `toolchainPrefix` field.
 
 ```jsonc
 {
@@ -59,15 +58,22 @@ ESP32 doesn't have a built-in JTAG interface, so you have to connect an external
 
 ## ESP32-C3
 
-Older versions with **revision < 3** **don't** have built-in JTAG interface.
+The availability of built-in JTAG interface depends on the ESP32-C3 revision:
 
-ESP32-C3 with **revision 3** **does** have a built-in JTAG interface, and you don't have to connect an external device to be able to debug. To get the chip revision, run the `cargo espflash board-info` command.
+- Revisions older than 3 **don't** have built-in JTAG interface.
+- Revitions 3 (and newer) **do** have a built-in JTAG interface, and you don't have to connect an external device to be able to debug.
+-
+To find your ESP32-C3 revision, run:
 
-### Hardware Setup
+```
+cargo espflash board-info
+# or
+espflash board-info
+```
 
-If your ESP32-C3's revision is lesser than 3, follow these instructions, if you have revision 3 you can jump to the [**Set up VSCode**](#set-up-vscode-1) step.
+### Configuration
 
-ESP32-C3 **revision 1** and **revision 2** don't have a built-in JTAG interface, so you have to connect an external JTAG adapter to the ESP32-C3 board, for example, [ESP-Prog](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html) can be used.
+1. (**Only for revisions older than 3**) Connect an external JTAG adapter, [ESP-Prog](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html) can be used.
 
 | ESP32-C3 Pin | JTAG Signal |
 | :----------: | :---------: |
@@ -79,13 +85,10 @@ ESP32-C3 **revision 1** and **revision 2** don't have a built-in JTAG interface,
 |     GND      |     GND     |
 
 **Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB.
-
-### Set up VSCode
-
-1. Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) extension for VScode.
-2. Create the `.vscode/launch.json` file in the project tree you want to debug. [This](https://github.com/esp-rs/esp32-hal/blob/master/.vscode/launch.json) can be used as a template file.
-3. Update **executable**, **svdFile**, **serverpath** paths, and **toolchainPrefix** field.
-
+2. Set up VSCode
+   1. Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) extension for VScode.
+   2. Create the `.vscode/launch.json` file in the project tree you want to debug. [This](https://github.com/esp-rs/esp32-hal/blob/master/.vscode/launch.json) can be used as a template file.
+   3. Update `executable`, `svdFile`, `serverpath` paths, and `toolchainPrefix` field.
 ```jsonc
 {
   // Use IntelliSense to learn about possible attributes.