[skip changelog]Fix typos and formatting in the documentation (#907)

* Fix typos in documentation

* Improve formatting of documentation

* Use correct case for Arduino CLI name in documentation

Co-authored-by: Roberto Sora <r.sora@arduino.cc>

Co-authored-by: Roberto Sora <r.sora@arduino.cc>

Author: per1234

Diff for: docs/CONTRIBUTING.md

@@ -50,7 +50,7 @@ From the project folder root, just run:
 task build
 ```
 
-The project uses Go modules so dependencies will be downloaded automatically; at the end of the build, you should find
+The project uses Go modules so dependencies will be downloaded automatically. At the end of the build, you should find
 an `arduino-cli` executable in the same folder.
 
 ## Running the tests
@@ -159,11 +159,11 @@ To keep the configurations tidy and in order we use [Prettier][prettier-website]
 in the project. Keeping and enforcing a formatting standard helps everyone make small PRs and avoids the introduction of
 formatting changes made by unconfigured editors.
 
-There are several ways to run Prettier, if you're using Visual Studio Code you can easily use the [`prettier-vscode`
+There are several ways to run Prettier. If you're using Visual Studio Code you can easily use the [`prettier-vscode`
 extension][prettier-vscode-extension] to automatically format as you write.
 
-Otherwise you can use the following tasks, to do so you'll need to install `npm` if not already installed. Check the
-[official documentation][npm-install-docs] to know how to install `npm` for your platform.
+Otherwise you can use the following tasks. To do so you'll need to install `npm` if not already installed. Check the
+[official documentation][npm-install-docs] to learn how to install `npm` for your platform.
 
 To check if the files are correctly formatted run:
 
@@ -177,7 +177,7 @@ If the output tells you that some files are not formatted correctly run:
 task config:format
 ```
 
-When opening a new Pull Requests checks are automatically run to verify that configuration files are correctly
+When opening a new Pull Request, checks are automatically run to verify that configuration files are correctly
 formatted. In case of failures we might ask you to update the PR with correct formatting.
 
 ## Working on docs
@@ -257,11 +257,11 @@ To keep the documentation tidy and in order we use [Prettier][prettier-website]
 files in the project. Keeping and enforcing a formatting standard helps everyone make small PRs and avoids the
 introduction of formatting changes made by unconfigured editors.
 
-There are several ways to run Prettier, if you're using Visual Studio Code you can easily use the [`prettier-vscode`
+There are several ways to run Prettier. If you're using Visual Studio Code you can easily use the [`prettier-vscode`
 extension][prettier-vscode-extension] to automatically format as you write.
 
-Otherwise you can use the following tasks, to do so you'll need to install `npm` if not already installed. Check the
-[official documentation][npm-install-docs] to know how to install `npm` for your platform.
+Otherwise you can use the following tasks. To do so you'll need to install `npm` if not already installed. Check the
+[official documentation][npm-install-docs] to learn how to install `npm` for your platform.
 
 To check if the files are correctly formatted run:
 
@@ -275,15 +275,15 @@ If the output tells you that some files are not formatted correctly run:
 task docs:format
 ```
 
-When opening a new Pull Requests checks are automatically run to verify that documentation is correctly formatted. In
+When opening a new Pull Request, checks are automatically run to verify that documentation is correctly formatted. In
 case of failures we might ask you to update the PR with correct formatting.
 
 ### Docs automation
 
 In order to avoid unwanted changes to the public website hosting the Arduino CLI documentation, only Mike is allowed to
 push changes to the `gh-pages` branch, and this only happens from within the CI, in a workflow named [publish-docs][11].
 
-The CI is responsible for guessing which version of the Arduino CLI we're building docs for, so that generated contents
+The CI is responsible for guessing which version of the Arduino CLI we're building docs for, so that generated content
 will be stored in the appropriate section of the documentation website. Because this guessing might be fairly complex,
 the logic is implemented in a Python script called [`build.py`][12]. The script will determine the version of the
 Arduino CLI that was modified in the current commit (either `dev` or an official, numbered release) and whether the
@@ -295,8 +295,8 @@ In order to support i18n in the CLI, any messages that are intended to be transl
 `i18n.Tr`. This call allows us to build a catalog of translatable strings, replacing the reference string at runtime
 with the localized value.
 
-Adding or modifying these messages requires an i18n update, as this process creates the reference catalog that are
-shared with translators. For that reason, the `task check` command will fail if the catalog was not updated to sync with
+Adding or modifying these messages requires an i18n update, as this process creates the reference catalog that is shared
+with translators. For that reason, the `task check` command will fail if the catalog was not updated to sync with
 changes to the source code.
 
 To update the catalog, execute the following command and commit the changes.

Diff for: docs/FAQ.md

@@ -19,7 +19,7 @@ Additional board options have to be separated by commas (instead of colon):
 
 ## Where is the Serial Monitor?
 
-Being this a command line tool we believe it's up to the user to choose their preferred way of interacting with the
+This being a command line tool, we believe it's up to the user to choose their preferred way of interacting with the
 serial connection. If we were to integrate it into the CLI we'd end up putting a tool inside a tool, and this would be
 something that we're trying to avoid.
 

Diff for: docs/index.md

@@ -11,7 +11,7 @@ Follow the [Getting started guide] to see how to use the most common CLI command
 
 ## Using the gRPC interface
 
-The [client_example] folder contains a sample program that shows how to use gRPC interface of the CLI. Available
+The [client_example] folder contains a sample program that shows how to use the gRPC interface of the CLI. Available
 services and messages are detailed in the [gRPC reference] pages.
 
 [installation]: installation.md

Diff for: docs/integration-options.md

@@ -25,16 +25,16 @@ programmatically - think about automation pipelines or a [CI][continuous integra
 system. There are some niceties to observe when you write software that’s supposed to be easy to run when unattended and
 one in particular is the ability to run without a configuration file. This is possible because every configuration
 option you find in the arduino-cli.yaml configuration file can be provided either through a command line flag or by
-setting an environment variable. To give an example, the following commands are all equivalent and will proceed fetching
-the unstable package index that can be used to work with experimental versions of cores:
+setting an environment variable. To give an example, the following commands are all equivalent and will fetch the
+package index used to work with unstable experimental versions of Arduino's cores:
 
 ![configuration methods screenshot][]
 
 See the [configuration documentation] for details about Arduino CLI's configuration system.
 
 Consistent with the previous paragraph, when it comes to providing output the Arduino CLI aims to be user friendly but
 also slightly verbose, something that doesn’t play well with robots. This is why we added an option to provide output
-that’s easy to parse, for example the following figure shows what getting the software version in [JSON] format looks
+that’s easy to parse. For example, the following figure shows what getting the software version in [JSON] format looks
 like.
 
 ![JSON output screenshot][]
@@ -70,15 +70,15 @@ Arduino CLI is written in [Golang] and the code is organized in a way that makes
 including the modules you need in another Golang application at compile time. Both the first and second pillars rely on
 a common Golang API, a set of functions that abstract all the functionalities offered by the Arduino CLI, so that when
 we provide a fix or a new feature, they are automatically available to both the command line and gRPC interfaces. The
-source modules implementing this API can be imported in other Golang programs to embed a full fledged Arduino CLI. For
+source modules implementing this API can be imported in other Golang programs to embed a full-fledged Arduino CLI. For
 example, this is how some backend services powering [Arduino Create] can compile sketches and manage libraries. Just to
 give you a taste of what it means to embed the Arduino CLI, here is how to search for a core using the API:
 
 ![Go library interface screenshot][]
 
-Embedding the Arduino CLI is limited to Golang applications and requires a deep knowledge of its internals; for the
-average use case the gRPC interface might be a better alternative, nevertheless this remains a valid option that we use
-and provide support for.
+Embedding the Arduino CLI is limited to Golang applications and requires a deep knowledge of its internals. For the
+average use case, the gRPC interface might be a better alternative. Nevertheless, this remains a valid option that we
+use and provide support for.
 
 ## Conclusions
 

Diff for: docs/library-specification.md

@@ -1,13 +1,13 @@
 This is the specification for the Arduino library format, to be used with Arduino IDE 1.5.x onwards.
 
 - rev.1 has been implemented starting with Arduino IDE version 1.5.3 (now superseded by rev.2)
-- rev.2 will be implemented starting from version Arduino IDE 1.5.6
-- rev.2.1 will be implemented starting from version Arduino IDE 1.6.10
-- rev.2.2 will be implemented starting from version Arduino IDE 1.8.10
+- rev.2 will be implemented starting from Arduino IDE version 1.5.6
+- rev.2.1 will be implemented starting from Arduino IDE version 1.6.10
+- rev.2.2 will be implemented starting from Arduino IDE version 1.8.10
 
 This new library format is intended to be used in tandem with **Library Manager**, available since Arduino IDE 1.6.2.
 The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy
-to use graphic interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and
+to use graphical interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and
 [Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11)
 as well as [`arduino-cli lib`](commands/arduino-cli_lib.md).
 
@@ -46,7 +46,7 @@ otherwise below, **all fields are required**. The available fields are:
   are now reserved for official Arduino libraries.
 - **version** - version of the library. Version should be [semver](http://semver.org/) compliant. 1.2.0 is correct; 1.2
   is accepted; r5, 003, 1.1c are invalid
-- **author** - name/nickname of the authors and their email addresses (not mandatory) separated by comma ","
+- **author** - name/nickname of the authors and their email addresses (not mandatory) separated by comma (,)
 - **maintainer** - name and email of the maintainer
 - **sentence** - a sentence explaining the purpose of the library
 - **paragraph** - a longer description of the library. The value of **sentence** will be prepended to this, so you
@@ -125,7 +125,8 @@ numbers, spaces ( ), underscores (\_), dots (.) and dashes (-). The maximum leng
 
 #### Source code
 
-For 1.5.x+-only libraries, the source code resides in the **src** folder. For example:
+For libraries intended to be used with Arduino IDE 1.5.x+ only, the source code resides in the **src** folder. For
+example:
 
     Servo/src/Servo.h
     Servo/src/Servo.cpp
@@ -149,7 +150,7 @@ from the **library root folder** and the **utility** folder, for example:
     Servo/utility/ServoTimers.h
     Servo/utility/ServoTimers.cpp
 
-This will allow existing 1.0 format libraries to compile under Arduino IDE 1.5.x+ as well and vice-versa. If a library
+This will allow existing 1.0 format libraries to compile under Arduino IDE 1.5.x+ as well, and vice-versa. If a library
 only needs to run on Arduino IDE 1.5.x+, we recommend placing all source code in the src/ folder. If a library requires
 recursive compilation of nested source folders, its code must be in the src/ folder (since Arduino IDE 1.0.x doesn’t
 support recursive compilation, backwards compatibility wouldn’t be possible anyway).
@@ -193,8 +194,8 @@ Servo/src/cortex-m4/fpv4-sp-d16-softfp/libServo.a
 
 #### Library Examples
 
-Library examples must be placed in the **examples** folder. Note that the **examples** folder must be written exactly
-like that (with lower case letters).
+Library examples must be placed in the **examples** folder. Note that the **examples** folder name must be written
+exactly like that (with lower case letters).
 
     Servo/examples/...
 
@@ -238,7 +239,7 @@ doSomething	KEYWORD2
 # Constants (LITERAL1)
 ```
 
-This file would cause the Arduino IDE to highlight `Test` as a DataType, and `doSomething` as a method / function.
+This file would cause the Arduino IDE to highlight `Test` as a data type, and `doSomething` as a method / function.
 
 #### keywords.txt format
 
@@ -311,8 +312,11 @@ A hypothetical library named "Servo" that adheres to the specification follows:
 Libraries placed in the `libraries` subfolder of the sketchbook folder (AKA "user directory") will be made available for
 all boards, which may include multiple different processor architectures. To provide architecture-specific code or
 optimizations, library authors can use the `ARDUINO_ARCH_XXX` preprocessor macro (`#define`), where XXX is the name of
-the architecture (as determined by the name of the folder containing it), e.g. `ARDUINO_ARCH_AVR` will be defined when
-compiling for AVR-based boards. For example,
+the architecture (as determined by the name of the
+[architecture folder](platform-specification.md#hardware-folders-structure) of the board's platform). For example,
+`ARDUINO_ARCH_AVR` will be defined when compiling for AVR-based boards.
+
+An example:
 
     #if defined(ARDUINO_ARCH_AVR)
       // AVR-specific code

Diff for: docs/package_index_json-specification.md

@@ -22,7 +22,7 @@ or
 
 `package_example.com_avr_boards_index.json`
 
-The index URL is periodically checked for updates so expect a constant flow of downloads (proportional to the number of
+The index URL is periodically checked for updates, so expect a constant flow of downloads (proportional to the number of
 active users).
 
 ## JSON Index file contents
@@ -146,7 +146,7 @@ array. In the example above `avr-gcc` comes with builds for:
 
 The IDE will take care to install the right flavour based on the `host` value, or fail if a needed flavour is
 missing.<br> Note that this information is not used to select the toolchain during compilation. If you want this
-specific version to be used, you should use the notation {runtime.tools.TOOLNAME-VERSION.path} in the platform.txt.
+specific version to be used, you should use the notation `{runtime.tools.TOOLNAME-VERSION.path}` in the platform.txt.
 
 The other fields are:
 
@@ -161,13 +161,13 @@ The other fields are:
 
 ##### How a tool's path is determined in platform.txt
 
-When the IDE needs a tool it downloads the corresponding archive file and unpacks the content into a private folder that
-can be referenced from `platform.txt` using one of the following properties:
+When the IDE needs a tool, it downloads the corresponding archive file and unpacks the content into a private folder
+that can be referenced from `platform.txt` using one of the following properties:
 
 - `{runtime.tools.TOOLNAME-VERSION.path}`
 - `{runtime.tools.TOOLNAME.path}`
 
-For example to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1-arduino5.path}` or
+For example, to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1-arduino5.path}` or
 `{runtime.tools.avr-gcc.path}`.
 
 ### Platforms definitions
@@ -223,7 +223,7 @@ The `version` field is validated by both Arduino IDE and [JSemVer](https://githu
 rules Arduino IDE follows for parsing versions
 ([source](https://github.com/arduino/Arduino/blob/master/arduino-core/src/cc/arduino/contributions/VersionHelper.java)):
 
-- Split the version at the - character and continue with the first part.
+- Split the version at the `-` character and continue with the first part.
 - If there are no dots (`.`), parse `version` as an integer and form a Version from that integer using
   `Version.forIntegers`
 - If there is one dot, split `version` into two, parse each part as an integer, and form a Version from those integers