Apply Vale lints (#111)

* docs: Apply vale lints

* docs: Mention Style Guide

* docs: Vale lints

* Grammarly suggestions (#112)

* docs: Apply review suggestions

.gitignore

@@ -1 +1,3 @@
 book
+.vale.ini
+.vale

README.md

@@ -4,22 +4,22 @@ This book is a work in progress.
 
 ## Quickstart
 
-This book is generated using [mdbook], and additionally uses the [mdbook-mermaid] preprocessor to add support for diagrams. To install these tools:
+This book is generated using [`mdbook`] and additionally uses the [`mdbook-mermaid`] preprocessor to add support for diagrams. To install these tools:
 
 ```shell
 cargo install mdbook mdbook-mermaid
 ```
 
-With `mdbook` and `mdbook-mermaid` installed you can clone the respository and start a development server by running:
+With `mdbook` and `mdbook-mermaid` installed, you can clone the repository and start a development server by running:
 
 ```shell
 git clone https://github.com/esp-rs/book
 cd book/
 mdbook serve
 ```
 
-[mdbook]: https://github.com/rust-lang/mdBook
-[mdbook-mermaid]: https://github.com/badboy/mdbook-mermaid
+[`mdbook`]: https://github.com/rust-lang/mdBook
+[`mdbook-mermaid`]: https://github.com/badboy/mdbook-mermaid
 
 ## License
 
@@ -39,3 +39,5 @@ The Rust on ESP Book is distributed under the following licenses:
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
 work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any
 additional terms or conditions.
+
+While contributing, please follow the [Rust Documentation Style Guide](rust-doc-style-guide.md).

rust-doc-style-guide.md

@@ -43,7 +43,7 @@ The style guide is based on the best practices collected from the following book
 
 ## Heading Titles
 
-The books on Rust usually have the heading titles based on nouns or gerunds:
+The books on Rust usually have heading titles based on nouns or gerunds:
 
 > **Design Patterns**<br>
 > **Using Structs to Structure Related Data**
@@ -113,7 +113,7 @@ Do NOT turn long phrases into links
 
   > ❌ See the [Rust Reference’s section on constant evaluation](https://doc.rust-lang.org/book/ch03-01-variables-and-mutability.html) for more information on what operations can be used when declaring constants.
 
-Also take into account the following
+Also, consider the following:
 
 - Do not provide a link to the same location repeatedly in the same or adjacent paragraphs without a good reason, especially using different link text.
 - Do not use the same link text to refer to different locations.

src/SUMMARY.md

@@ -6,14 +6,14 @@
   - [Using the Core Library (`no_std`)](./overview/using-the-core-library.md)
 - [Setting Up a Development Environment](./installation/index.md)
   - [Rust installation](./installation/rust.md)
-  - [RISC-V targets only](./installation/riscv.md)
-  - [RISC-V and Xtensa targets](./installation/riscv-and-xtensa.md)
+  - [`RISC-V` targets only](./installation/riscv.md)
+  - [`RISC-V` and `Xtensa` targets](./installation/riscv-and-xtensa.md)
   - [`std` Development Requirements](./installation/std-requirements.md)
   - [Using Containers](./installation/using-containers.md)
 - [Writing Your Own Application](./writing-your-own-application/index.md)
   - [Generating Projects from Templates](./writing-your-own-application/generate-project/index.md)
-    - [Understanding esp-template](./writing-your-own-application/generate-project/esp-template.md)
-    - [Understanding esp-idf-template](./writing-your-own-application/generate-project/esp-idf-template.md)
+    - [Understanding `esp-template`](./writing-your-own-application/generate-project/esp-template.md)
+    - [Understanding `esp-idf-template`](./writing-your-own-application/generate-project/esp-idf-template.md)
   - [Writing `no_std` Applications](./writing-your-own-application/nostd.md)
   - [Writing `std` Applications](./writing-your-own-application/std.md)
 - [Tooling](./tooling/index.md)

src/installation/riscv-and-xtensa.md

@@ -1,4 +1,4 @@
-# RISC-V and Xtensa targets
+# `RISC-V` and `Xtensa` Targets
 
 [`espup`][espup-github] is a tool that simplifies installing and maintaining the components required to develop Rust applications for the `Xtensa` and `RISC-V` architectures.
 
@@ -9,13 +9,13 @@ To install `espup`, run:
 cargo install espup
 ```
 
-You can also directly download pre-compiled [release binaries] or use [cargo-binstall].
+You can also directly download pre-compiled [release binaries][release-binaries] or use [`cargo-binstall`][cargo-binstall].
 
 [espup-github]: https://github.com/esp-rs/espup
-[release binaries]: https://github.com/esp-rs/espup/releases
+[release-binaries]: https://github.com/esp-rs/espup/releases
 [cargo-binstall]: https://github.com/cargo-bins/cargo-binstall
 
-### 2. Install necessary toolchains
+### 2. Install Necessary Toolchains
 
 Install all the necessary tools to develop Rust applications for all supported Espressif targets by running:
 ```shell
@@ -26,7 +26,7 @@ espup install
 
 [rust-esp-book-std-requirements]: ./std-requirements.md
 
-### 3. Set up the environment variables
+### 3. Set Up the Environment Variables
 `espup` will create an export file that contains some environment variables required to build projects.
 
 On Windows (`%USERPROFILE%\export-esp.ps1`)
@@ -48,7 +48,7 @@ On Unix-based systems (`$HOME/export-esp.sh`). There are different ways of sourc
 
    This approach **does not** require any sourcing. The `export-esp.sh` script will be sourced automatically in every shell.
 
-### What espup Installs
+### What `espup` Installs
 
 To enable support for Espressif targets, `espup` installs the following tools:
 
@@ -71,10 +71,10 @@ If you run into an error, please, check the [Troubleshooting][troubleshooting] c
 [llvm-github-fork-upstream issue]: https://github.com/espressif/llvm-project/issues/4
 [troubleshooting]: ../misc/troubleshooting.md
 
-### Other installation methods for Xtensa targets
+### Other Installation Methods for `Xtensa` Targets
 
-- Using [esp-rs/rust-build] installation scripts. This was the recommended way in the past, but now the installation scripts are feature frozen, and all new features will only be included in `espup`. See the repository README for instructions.
-- Building the Rust compiler with `Xtensa` support from source. This process is computationally expensive and can take one or more hours to complete depending on your system. It is not recommended unless there is a major reason to go for this approach. Here is the repository to build it from source: [esp-rs/rust repository].
+- Using [`rust-build`][rust-build] installation scripts. This was the recommended way in the past, but now the installation scripts are feature frozen, and all new features will only be included in `espup`. See the repository README for instructions.
+- Building the Rust compiler with `Xtensa` support from source. This process is computationally expensive and can take one or more hours to complete depending on your system. It is not recommended unless there is a major reason to go for this approach. Here is the repository to build it from source: [`esp-rs/rust` repository][esp-rs-rust].
 
-[esp-rs/rust-build]: https://github.com/esp-rs/rust-build#download-installer-in-bash
-[esp-rs/rust repository]: https://github.com/esp-rs/rust
+[rust-build]: https://github.com/esp-rs/rust-build#download-installer-in-bash
+[esp-rs-rust]: https://github.com/esp-rs/rust

src/installation/riscv.md

@@ -1,4 +1,4 @@
-# RISC-V targets only
+# `RISC-V` Targets Only
 
 To build Rust applications for the Espressif chips based on `RISC-V` architecture, do the following:
 
@@ -15,7 +15,7 @@ To build Rust applications for the Espressif chips based on `RISC-V` architectur
       rustup target add riscv32imac-unknown-none-elf # For ESP32-C6 and ESP32-H2
       ```
 
-      This target is currently [Tier 2][rust-lang-book--platform-support-tier2]; note the different flavors of `riscv32` target in Rust covering different [`RISC-V` extensions][wiki-riscv-standard-extensions].
+      This target is currently [Tier 2][rust-lang-book--platform-support-tier2]. Note the different flavors of `riscv32` target in Rust covering different [`RISC-V` extensions][wiki-riscv-standard-extensions].
 
     - For `std` applications:
 

src/installation/rust.md

@@ -1,4 +1,4 @@
-# Rust installation
+# Rust Installation
 
 Make sure you have [Rust][rust-lang-org] installed. If not, see the instructions on the [rustup][rustup.rs-website] website.
 

src/installation/std-requirements.md

@@ -1,4 +1,4 @@
-# `std`  Development Requirements
+# `std` Development Requirements
 
 Regardless of the target architecture, make sure you have the following required tools installed to build [`std`][rust-esp-book-overview-std] applications:
 
@@ -9,7 +9,7 @@ Regardless of the target architecture, make sure you have the following required
     cargo install ldproxy
     ```
 
-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.
+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.
 
 [rust-esp-book-overview-std]: ../overview/using-the-standard-library.md
 [python-website-download]: https://www.python.org/downloads/

src/installation/using-containers.md

@@ -7,7 +7,7 @@ You can find numerous tags for `linux/arm64`, and `linux/amd64` platforms.
 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.
+  - 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:
 

src/introduction.md

@@ -10,7 +10,7 @@ For tools and libraries relating to Rust on ESP, please see the [esp-rs organiza
 [espressif]: https://espressif.com/
 [esp-rs]: https://github.com/esp-rs/
 
-## Who This Book is For
+## Who This Book Is For
 
 This book is intended for people with some experience in Rust and also assumes rudimentary knowledge of embedded development and electronics. For those without prior experience, we recommend first reading the [Assumptions and Prerequisites][prerequisites] and [Resources][resources] sections to get up to speed.
 
@@ -31,7 +31,7 @@ This book is intended for people with some experience in Rust and also assumes r
 
 ### 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.
+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.
 
 | Resource                                     | Description                                                                          |
 | -------------------------------------------- | ------------------------------------------------------------------------------------ |
@@ -52,31 +52,31 @@ This book is currently available in English only. Once the contents of the book
 
 ## How to Use This Book
 
-This book generally assumes that you are reading it front-to-back; content covered in later chapters may not make sense without context from previous chapters.
+This book assumes that you are reading it front-to-back. Content covered in later chapters may not make much sense without the context from previous chapters.
 
 ## Contributing to This Book
 
 The work on this book is coordinated in [this repository][book-repository].
 
-If you have trouble following the instructions in this book or find that some section of the book is not clear enough or hard to follow, then that's a bug, and it should be reported in [the issue tracker][book-issues] of this book.
+If you have trouble following the instructions in this book or find that some section of the book is not clear enough, then that's a bug. Please report it in [the issue tracker][book-issues] of this book.
 
-Pull requests fixing typos and adding new content are very welcome!
+Pull requests fixing typos and adding new content are welcome!
 
 [book-issues]: https://github.com/esp-rs/book/issues/
 [book-repository]: https://github.com/esp-rs/book
 
-## Re-using This Material
+## Re-Using This Material
 
 This book is distributed under the following licenses:
 
 - The code samples and freestanding Cargo projects contained within this book are licensed under the terms of both the [MIT License][mit-license] and the [Apache License v2.0][apache-license].
 - The written prose, pictures, and diagrams contained within this book are licensed under the terms of the Creative Commons [CC-BY-SA v4.0][cc-license] license.
 
-TL;DR: If you want to use our text or images in your work, you need to:
+In summary, to use our text or images in your work, you need to:
 
 - Give the appropriate credit (i.e. mention this book on your slide, and provide a link to the relevant page)
-- Provide a link to the [CC-BY-SA v4.0][cc-license] licence
-- Indicate if you have changed the material in any way, and make any changes to our material available under the same licence
+- Provide a link to the [CC-BY-SA v4.0][cc-license] license
+- Indicate if you have changed the material in any way, and make any changes to our material available under the same license
 
 Please do let us know if you find this book useful!
 

src/misc/troubleshooting.md

@@ -2,7 +2,7 @@
 
 Here, we will present a list of common errors that may appear when building a project alongside the reason and a solution to them.
 
-## Environment variable LIBCLANG_PATH not set
+## Environment Variable `LIBCLANG_PATH` Not Set
 
 ```text
 thread 'main' panicked at 'Unable to find libclang: "couldn't find any valid shared libraries matching: ['libclang.so', 'libclang-*.so', 'libclang.so.*', 'libclang-*.so.*'], set the `LIBCLANG_PATH` environment variable to a path where one of these files can be found (invalid: [])"', /home/esp/.cargo/registry/src/github.com-1ecc6299db9ec823/bindgen-0.60.1/src/lib.rs:2172:31
@@ -31,7 +31,7 @@ cargo install ldproxy
 [`ldproxy`]: https://github.com/esp-rs/embuild/tree/master/ldproxy
 [rust-esp-book-std-requirements]: ./../installation/std-requirements.md
 
-## Using a wrong Rust toolchain
+## Using the Wrong Rust Toolchain
 
 ```text
 $ cargo build
@@ -43,7 +43,7 @@ Caused by:
   error: Error loading target specification: Could not find specification for target "xtensa-esp32-espidf". Run `rustc --print target-list` for a list of built-in targets
 ```
 
-If you are encountering the previous error or a similar one, you are probably not using the proper Rust toolchain, remember that for Xtensa targets, you need to use Espressif Rust fork toolchain, there are several ways to do it:
+If you are encountering the previous error or a similar one, you are probably not using the proper Rust toolchain. Remember that for `Xtensa` targets, you need to use Espressif Rust fork toolchain, there are several ways to do it:
 - A [toolchain override] shorthand used on the command-line: `cargo +esp`.
 - Set `RUSTUP_TOOLCHAIN` environment variable to `esp`.
 - Set a [directory override]: `rustup override set esp`
@@ -64,7 +64,7 @@ For more information on toolchain overriding, see the [Overrides chapter of The
 
 ## Windows
 
-### Long path names
+### Long Path Names
 
 When using Windows, you may encounter issues building a new project if using long path names. Follow these steps to substitute the path of your project:
 ```powershell
@@ -98,7 +98,7 @@ If using GNU ABI, install [MinGW/MSYS2 toolchain].
 
 ## FAQ
 
-### I updated my `sdkconfig.defaults` file but it doesn't appear to have had any effect
+### `sdkconfig.defaults` File is Updated but it Doesn't Appear to Have Had Any Effect
 
 You must clean your project and rebuild for changes in the `sdkconfig.defaults` to take effect:
 
@@ -107,9 +107,9 @@ cargo clean
 cargo build
 ```
 
-### The documentation for the crates mentioned on this page is out of date or missing
+### The Documentation for the Crates Mentioned on This Page is out of Date or Missing
 
-Due to the [resource limits] imposed by [docs.rs], internet access is blocked while building documentation and as such we are unable to build the documentation for `esp-idf-sys` or any crate depending on it.
+Due to the [resource limits] imposed by [docs.rs], internet access is blocked while building documentation. For this reason, we are unable to build the documentation for `esp-idf-sys` or any crate depending on it.
 
 Instead, we are building the documentation and hosting it ourselves on GitHub Pages:
 
@@ -123,17 +123,17 @@ Instead, we are building the documentation and hosting it ourselves on GitHub Pa
 [`esp-idf-svc` documentation]: https://esp-rs.github.io/esp-idf-svc/esp_idf_svc/
 [`esp-idf-sys` documentation]: https://esp-rs.github.io/esp-idf-sys/esp_idf_sys/
 
-### \*\*\*ERROR\*\*\* A stack overflow in task main has been detected.
+### A Stack Overflow in Task `main` has Been Detected
 
 If the second-stage bootloader reports this error, you likely need to increase the stack size for the main task. This can be accomplished by adding the following to the `sdkconfig.defaults` file:
 
 ```text
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000
 ```
 
-In this example, we are allocating 7kB for the main task's stack.
+In this example, we are allocating 7 kB for the main task's stack.
 
-### How can I completely disable the watchdog timer(s)?
+### How to Disable Watchdog Timer(s)?
 
 Add to your `sdkconfig.defaults` file:
 

src/overview/index.md

@@ -19,7 +19,7 @@ The [esp-rs organization] on GitHub is home to several repositories related to r
 [embedded-rust-book-intro-std]: https://docs.rust-embedded.org/book/intro/no-std.html#a-no_std-rust-environment
 [esp-rs organization]: https://github.com/esp-rs/
 
-## Repository naming convention
+## Repository Naming Convention
 
 In the [esp-rs organization], we use the following wording:
 - Repositories starting with `esp-` are focused on `no_std` approach. For example, `esp-hal`