[skip changelog]Make general minor improvements to the wording of the documentation (#906)

* Restructure paragraph re: standardizing architecture names

The information about architecture values being case sensitive was placed in the middle of a largely unrelated paragraph.

The paragraph about using standardized architecture names had an overly strident tone, which I have softened.

* Improve wording of documentation

Do some minor rewording of sentences to improve clarity and readability, but without changing their informational content.

Author: per1234

cli/compile/compile.go

@@ -84,7 +84,7 @@ func NewCommand() *cobra.Command {
 	command.Flags().StringVar(&vidPid, "vid-pid", "", "When specified, VID/PID specific build properties are used, if board supports them.")
 	command.Flags().StringSliceVar(&libraries, "libraries", []string{},
 		"List of custom libraries paths separated by commas. Or can be used multiple times for multiple libraries paths.")
-	command.Flags().BoolVar(&optimizeForDebug, "optimize-for-debug", false, "Optional, optimize compile output for debug, not for release.")
+	command.Flags().BoolVar(&optimizeForDebug, "optimize-for-debug", false, "Optional, optimize compile output for debugging, rather than for release.")
 	command.Flags().StringVarP(&programmer, "programmer", "P", "", "Optional, use the specified programmer to upload.")
 
 	return command

docs/library-specification.md

@@ -49,9 +49,9 @@ otherwise below, **all fields are required**. The available fields are:
 - **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** always will be prepended, so you should
-  start by writing the second sentence here
-- **category** - (defaults to `Uncategorized`) if present, one of these:
+- **paragraph** - a longer description of the library. The value of **sentence** will be prepended to this, so you
+  should start by writing the second sentence here
+- **category** - (defaults to `Uncategorized`) allowed values:
   - Display
   - Communication
   - Signal Input/Output
@@ -213,7 +213,7 @@ Remember that files placed inside this folder will increase the size of the libr
 that weights a few kilobytes may not be such a good idea.
 
 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.
+inside.
 
 ### Keywords
 

docs/package_index_json-specification.md

@@ -156,8 +156,8 @@ The other fields are:
 - `size`: the size of the archive in bytes
 - `checksum`: the checksum of the archive, used to check if the file has been corrupted. The format is
   `ALGORITHM:CHECKSUM`, currently `MD5`, `SHA-1`,`SHA-256` algorithm are supported, we recommend `SHA-256`. On \*nix or
-  MacOSX you may be able to use the command `shasum -a 256 filename` to generate SHA-256 checksums. There are many free
-  options for Windows including md5deep, there are also online utilities for generating checksums.
+  macOS you can use the command `shasum -a 256 filename` to generate SHA-256 checksums. There are free options for
+  Windows, including md5deep. There are also online utilities for generating checksums.
 
 ##### How a tool's path is determined in platform.txt
 
@@ -307,7 +307,7 @@ cause the Arduino IDE to no longer load until you have deleted the file from you
 ```
 
 In the example there is one `PACKAGE`, My Board. The package is compatible with the AVR architecture. There are two
-versions of the `PACKAGE`, 1.0.0 and 1.0.1. No `TOOLS` needed to be installed so that section was left blank.
+versions of the `PACKAGE`, 1.0.0 and 1.0.1. No `TOOLS` needed to be installed so that section was left empty.
 
 Here is the Boards Manager entry created by the example: ![Boards Manager screenshot](img/boards-manager-screenshot.png)
 

docs/platform-specification.md

@@ -20,11 +20,12 @@ A vendor/maintainer can have multiple supported architectures. For example, belo
 
 The vendor "arduino" has two supported architectures (AVR and SAM), while "xxxxx" and "yyyyy" have only AVR.
 
-If possible, follow existing architecture name conventions when creating hardware packages. The architecture folder name
-is used to determine library compatibility and also to permit referencing resources from another core of the same
-architecture so using a non-standard architecture name can only be harmful to your users. Architecture values are case
-sensitive (e.g. `AVR` != `avr`). Use the vendor folder name to differentiate your package, **NOT** the architecture
-name.
+Architecture values are case sensitive (e.g. `AVR` != `avr`).
+
+If possible, follow existing architecture name conventions when creating hardware packages. Use the vendor folder name
+to differentiate your package. The architecture folder name is used to determine library compatibility and to permit
+referencing resources from another core of the same architecture, so use of a non-standard architecture name can have a
+harmful effect.
 
 ## Architecture configurations
 
@@ -313,8 +314,8 @@ error.
 
 If **recipe.preproc.macros** is not defined, it is automatically generated from **recipe.cpp.o.pattern**.
 
-Note that older Arduino IDE versions used the **recipe.preproc.includes** recipe to determine includes, which is
-undocumented here. Since Arduino IDE 1.6.7 (arduino-builder 1.2.0) this was changed and **recipe.preproc.includes** is
+Note that older Arduino IDE versions used the **recipe.preproc.includes** recipe (which is not documented here) to
+determine includes. Since Arduino IDE 1.6.7 (arduino-builder 1.2.0) this was changed and **recipe.preproc.includes** is
 no longer used.
 
 #### Pre and post build hooks (since Arduino IDE 1.6.5)

docs/sketch-build-process.md

@@ -102,10 +102,10 @@ The "folder name priority" is determined as follows (in order of highest to lowe
 
 The "location priority" is determined as follows (in order of highest to lowest priority):
 
-1. The library is in a custom libraries path specified via the
+1. The library is under a custom libraries path specified via the
    [`--libraries` option](commands/arduino-cli_compile.md#options) of `arduino-cli compile` (in decreasing order of
    priority when multiple custom paths are defined)
-1. The library is in the `libraries` subfolder of the IDE's sketchbook or Arduino CLI's user directory
+1. The library is under the `libraries` subfolder of the IDE's sketchbook or Arduino CLI's user directory
 1. The library is bundled with the board platform/core
    ([`{runtime.platform.path}/libraries`](platform-specification.md#global-predefined-properties))
 1. The library is bundled with the [referenced](platform-specification.md#referencing-another-core-variant-or-tool)