arduino · rsora · Apr 17, 2020 · Apr 12, 2020
diff --git a/docs/library-specification.md b/docs/library-specification.md
@@ -1,14 +1,15 @@
 This is the specification for the 3rd party library format to be used with Arduino IDE 1.5.x onwards.
 
-* rev.1 has been implemented starting with IDE version 1.5.3 (now superseded by rev.2)
-* rev.2 will be implemented starting from version 1.5.6
-* rev.2.1 will be implemented starting from version 1.6.10
-* rev.2.2 will be implemented starting from version 1.8.10
+* 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
+
+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 [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`](https://arduino.github.io/arduino-cli/commands/arduino-cli_lib/). It doesn't yet take care of dependencies between libraries.
 
-This new library format is intended to be used in tandem with the Arduino IDE's **Library Manager**, available since version 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. It doesn't yet take care of dependencies between libraries.
 More information about how Library Manager works is available [here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
 
-Arduino IDE 1.5.x+ supports multiple microcontroller architectures (e.g. AVR, SAM, etc), meaning that libraries may need to work on multiple architectures. The new 1.5 library format doesn’t contain special support for cross-architecture libraries, but it does provide a preprocessor based mechanism for libraries to target sections of code to specific architectures.
+Arduino development software supports multiple microcontroller architectures (e.g. AVR, SAM, etc), meaning that libraries may need to work on multiple architectures. The new 1.5 library format doesn’t contain special support for cross-architecture libraries, but it does provide a preprocessor based mechanism for libraries to target sections of code to specific architectures.
 
 ## See also
 
@@ -46,10 +47,10 @@ The library.properties file is a key=value properties list. Every field in this
     * Other
 * **url** - the URL of the library project, for a person to visit. For example, the library's GitHub page. This is used for the "More info" links in Library Manager
 * **architectures** - (defaults to `*`) a comma separated list of architectures supported by the library. If the library doesn’t contain architecture specific code use `*` to match all architectures. This field is used as one factor in determining priority when multiple libraries match an `#include` directive and to provide a warning message when the library is compiled for a board of an architecture that doesn't match any on the list.
-* **depends** - **(available from Arduino IDE 1.8.10)** (optional) a comma-separated list of dependencies (libraries that are needed to build the current library). Library Manager will offer to install the dependencies during installation of the library. Since spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the name without ambiguity for example:<br>
+* **depends** - **(available from Arduino IDE 1.8.10/Arduino CLI 0.7.0)** (optional) a comma-separated list of dependencies (libraries that are needed to build the current library). The Arduino IDE's Library Manager will offer to install the dependencies during installation of the library. [`arduino-cli lib install`](https://arduino.github.io/arduino-cli/commands/arduino-cli_lib_install/) will automatically install the dependencies. Since spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the name without ambiguity for example:<br>
 `depends=Very long library name, Another library with long-name`
 * **dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to `true`, the library will be compiled using a .a (archive) file. First, all source files are compiled into .o files as normal. Then instead of including all .o files in the linker command directly, all .o files are saved into a .a file, which is then included in the linker command. [1.5 format library folder structure](#layout-of-folders-and-files) is required.
-* **includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the sketch as `#include <...>` lines. This property is used with the "Include library" command in the IDE. If the `includes` property is missing, all the header files (.h) on the root source folder are included.
+* **includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the sketch as `#include <...>` lines. This property is used with the "Include library" command in the Arduino IDE. If the `includes` property is missing, all the header files (.h) on the root source folder are included.
 * **precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) set to `true` to allow the use of .a (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where `{build.mcu}` is the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. The static library should be linked as an ldflag.
 * **ldflags** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) the linker flags to be added. Ex: `ldflags=-lm`
 
@@ -82,30 +83,30 @@ For 1.5.x+-only libraries, the source code resides in the **src** folder. For ex
     Servo/src/Servo.h
     Servo/src/Servo.cpp
 
-The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the "Sketch > Include Library" menu), an `#include` statement will be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder.
+The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the Arduino IDE's "Sketch > Include Library" menu or the Arduino Web Editor's "Include" button), an `#include` statement will be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder.
 
-For backward compatibility with Arduino 1.0.x, the library author may opt to place source code into the root folder, instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched from the **library root folder** and the **utility** folder, for example:
+For backward compatibility with Arduino IDE 1.0.x, the library author may opt to place source code into the root folder, instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched from the **library root folder** and the **utility** folder, for example:
 
     Servo/Servo.h
     Servo/Servo.cpp
     Servo/utility/ServoTimers.h
     Servo/utility/ServoTimers.cpp
 
-This will allow existing 1.0.x libraries to compile under 1.5.x+ as well and vice-versa. If a library only needs to run on 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 1.0.x doesn’t support recursive compilation, backwards compatibility wouldn’t be possible anyway).
+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).
 
 #### 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).
 
     Servo/examples/...
 
-Sketches contained inside the examples folder will be shown in the Examples menu of the IDE.
+Sketches contained inside the examples folder will be shown in the Examples menu of the Arduino IDE and Arduino Web Editor.
 
 #### Extra documentation
 
 An **extras** folder can be used by the developer to put documentation or other items to be bundled with the library. Remember that files placed inside this folder will increase the size of the library, so putting a 20MB PDF in a library that weights a few kilobytes may not be such a good idea.
 
-The content of the *extras* folder is totally ignored by the IDE; you are free to put anything inside such as supporting documentation, etc.
+The content of the *extras* folder is totally ignored by the Arduino development software; you are free to put anything inside such as supporting documentation, etc.
 
 ### Keywords
 
@@ -145,7 +146,7 @@ KEYWORD_TOKENTYPE | Use for | Theme property
 `LITERAL2` | ? | `editor.function.style`
 
 ##### `REFERENCE_LINK`
-This field specifies the [Arduino Language Reference](https://www.arduino.cc/reference/en) page to open via **Right Click > Find in Reference** or **Help > Find in Reference** when the cursor is on that keyword. Generally it does not make sense to define the `REFERENCE_LINK` field for 3rd party library keywords since they are not likely to be in the Arduino Language Reference.
+This field specifies the [Arduino Language Reference](https://www.arduino.cc/reference/en) page to open via the Arduino IDE's **Right Click > Find in Reference** or **Help > Find in Reference** when the cursor is on that keyword. Generally it does not make sense to define the `REFERENCE_LINK` field for 3rd party library keywords since they are not likely to be in the Arduino Language Reference.
 
 ##### `RSYNTAXTEXTAREA_TOKENTYPE`
 In Arduino IDE 1.6.5 and newer this field overrides `KEYWORD_TOKENTYPE`. In previous IDE versions the `RSYNTAXTEXTAREA_TOKENTYPE` field is ignored and `KEYWORD_TOKENTYPE` is used instead.
@@ -181,7 +182,7 @@ A hypothetical library named "Servo" that adheres to the specification follows:
 
 ## Working with multiple architectures
 
-In 1.5.x+, libraries placed in the user’s sketchbook folder (in the libraries/ subfolder) 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,
+Libraries placed in the user’s sketchbook folder (in the libraries/ subfolder) 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,
 
     #if defined(ARDUINO_ARCH_AVR)
       // AVR-specific code
@@ -203,4 +204,4 @@ Alternatively, if a library only works on certain architectures, you can provide
 
 ## Old library format (pre-1.5)
 
-In order to support old libraries (from Arduino 1.0.x), Arduino 1.5.x+ will also compile libraries missing a library.properties metadata file. As a result, these libraries should behave as they did in Arduino 1.0.x, although they will be available for all boards, including non-AVR ones (which wouldn’t have been present in 1.0.x).
+In order to support old libraries (from Arduino IDE 1.0.x), the Arduino IDE/Pro IDE and Arduino CLI will also compile libraries missing a library.properties metadata file. As a result, these libraries should behave as they did in Arduino IDE 1.0.x, although they will be available for all boards, including non-AVR ones (which wouldn’t have been present in Arduino IDE 1.0.x).
diff --git a/docs/package_index_json-specification.md b/docs/package_index_json-specification.md
@@ -1,12 +1,14 @@
-Starting from version 1.6.4 the Boards Manager of the Arduino IDE can be used to automatically install support for **3rd party hardware** by simply entering an URL in the **File > Preferences** dialog. The URL must be provided by the 3rd party hardware producer and should point to a JSON file that contains an index of the boards available to install and the location of the installation archives. Boards Manager also allows easy updates of installed Boards when new versions are released.
+Introduced in Arduino IDE 1.6.4, Boards Manager makes it easy to install and update Arduino platforms. In order to provide Boards Manager installation support for a platform, a JSON formatted index file must be published. This is the specification for that file.
+
+Boards Manager functionality is provided by [Arduino CLI](getting-started.md#adding-3rd-party-cores), [Arduino IDE](https://www.arduino.cc/en/Guide/Cores), and Arduino Pro IDE.
 
 ## Naming of the JSON index file
 
-The IDE may use many different index files coming from different vendors, so each vendor should name his own index file in a way that won't conflict with others. The file must be named as follows:
+Many different index files coming from different vendors may be in use, so each vendor should name his own index file in a way that won't conflict with others. The file must be named as follows:
 
 `package_YOURNAME_PACKAGENAME_index.json`
 
-The prefix `package_` and the postfix `_index.json` are **mandatory** (otherwise the index file is not recognised by the IDE) while the choice of `YOURNAME_PACKAGENAME` is left to the packager.
+The prefix `package_` and the postfix `_index.json` are **mandatory** (otherwise the index file is not recognised by the Arduino development software) while the choice of `YOURNAME_PACKAGENAME` is left to the packager.
 We suggest using a domain name owned by the packager. For example:
 
 `package_arduino.cc_index.json`
@@ -58,8 +60,8 @@ The root of the JSON index is an array of `packages`:
 The metadata fields are:
 
 * `name`: the folder used for the installed cores. The [vendor folder](platform-specification.md#hardware-folders-structure) name of the installed package is determined by this field
-* `maintainer`: the extended name of the vendor that is displayed on the Boards Manager GUI
-* `websiteURL`: the URL to the vendor's website, appears on the Boards Manager as a "More info" link
+* `maintainer`: the extended name of the vendor that is displayed on the Arduino IDE/Pro IDE's Boards Manager GUI
+* `websiteURL`: the URL to the vendor's website, appears on the Arduino IDE/Pro IDE's Boards Manager as a "More info" link
 * `email`: the email of the vendor/maintainer
 
 Now, before looking at `PLATFORMS`, let's explore first how `TOOLS` are made.
@@ -136,7 +138,7 @@ Each tool version may come in different build flavours for different OS. Each fl
 * Mac (`i386-apple-darwin11`)
 
 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 the IDE does not use this information to select the toolchain during verify. If you want the IDE to use this specific version you should use the notation {runtime.tools.TOOLNAME-VERSION.path} in the platform.txt.
+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.
 
 The other fields are:
 
@@ -194,9 +196,9 @@ Each PLATFORM describes a core for a specific architecture. The fields needed ar
 * `architecture`: is the architecture of the plaftorm (avr, sam, etc...). It must match the architecture of the core as explained in the [Arduino platform specification](platform-specification.md#hardware-folders-structure)
 * `version`: the version of the platform.
 * `category`: this field is reserved, a 3rd party core must set it to `Contributed`
-* `help`/`online`: is a URL that is displayed on the Boards Manager as an "Online Help" link
+* `help`/`online`: is a URL that is displayed on the Arduino IDE's Boards Manager as an "Online Help" link
 * `url`, `archiveFileName`, `size` and `checksum`: metadata of the core archive file. The meaning is the same as for the TOOLS
-* `boards`: the list of boards supported (note: just the names to display on the GUI! the real boards definitions are inside `boards.txt` inside the core archive file)
+* `boards`: the list of boards supported (note: just the names to display on the Arduino IDE and Arduino Pro IDE's Boards Manager GUI! the real boards definitions are inside `boards.txt` inside the core archive file)
 * `toolsDependencies`: the tools needed by this core. Each tool is referenced by the triple (`packager`, `name`, `version`) as previously said. Note that you can reference tools available in other packages as well.
 
 The `version` field is validated by both Arduino IDE and [JSemVer](https://github.com/zafarkhaja/jsemver). Here are the rules Arduino IDE follows for parsing versions ([source](https://github.com/arduino/Arduino/blob/master/arduino-core/src/cc/arduino/contributions/VersionHelper.java)):
@@ -295,7 +297,7 @@ Here is the Boards Manager entry created by the example:
 
 The installation archives contain the Board support files. Supported formats are .zip, .tar.bz2, and .tar.gz.
 
-The folder structure of the core archive is slightly different from the standard manually installed Arduino 1.5+ compatible hardware folder structure. You must remove the architecture folder(e.g., `avr` or `arm`), moving all the files and folders within the architecture folder up a level.
+The folder structure of the core archive is slightly different from the standard manually installed Arduino IDE 1.5+ compatible hardware folder structure. You must remove the architecture folder(e.g., `avr` or `arm`), moving all the files and folders within the architecture folder up a level.
 
 ***