From a9440910f420108c56d93da6684132cca95f99f4 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 18 Aug 2020 02:52:09 -0700 Subject: [PATCH 1/3] Fix typos in documentation --- docs/CONTRIBUTING.md | 24 ++++----- docs/FAQ.md | 2 +- docs/index.md | 2 +- docs/integration-options.md | 14 ++--- docs/library-specification.md | 28 +++++----- docs/package_index_json-specification.md | 8 +-- docs/platform-specification.md | 66 ++++++++++++------------ docs/sketch-build-process.md | 6 +-- docs/sketch-specification.md | 8 +-- rpc/commands/board.pb.go | 2 +- rpc/commands/board.proto | 2 +- rpc/monitor/monitor.proto | 2 +- 12 files changed, 84 insertions(+), 80 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3ca764bbf4d..ede023271da 100644 --- a/docs/CONTRIBUTING.md +++ b/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,7 +275,7 @@ 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 @@ -283,7 +283,7 @@ case of failures we might ask you to update the PR with correct formatting. 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 --git a/docs/FAQ.md b/docs/FAQ.md index 33e1505db8f..d022190d3d1 100644 --- a/docs/FAQ.md +++ b/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 --git a/docs/index.md b/docs/index.md index 6d6f89954dd..0b8d6d21493 100644 --- a/docs/index.md +++ b/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 --git a/docs/integration-options.md b/docs/integration-options.md index 47be96ac40c..f5303ee6857 100644 --- a/docs/integration-options.md +++ b/docs/integration-options.md @@ -25,8 +25,8 @@ 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][] @@ -34,7 +34,7 @@ See the [configuration documentation] for details about Arduino CLI's configurat 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 --git a/docs/library-specification.md b/docs/library-specification.md index af9fff2db5f..822c8f4bbb4 100644 --- a/docs/library-specification.md +++ b/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 --git a/docs/package_index_json-specification.md b/docs/package_index_json-specification.md index 9766091bdf9..3b9937d8067 100644 --- a/docs/package_index_json-specification.md +++ b/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 @@ -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 diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 4a27b84e619..18dfcd1446c 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -47,8 +47,8 @@ of another property by putting its name inside brackets "{" "}". For example: [....] recipe.c.o.pattern={compiler.path}{compiler.c.cmd} -In this example the property **recipe.c.o.pattern** will be set to **/tools/g++\_arm_none_eabi/bin/arm-none-eabi-gcc** -that is the composition of the two properties **compiler.path** and **compiler.c.cmd**. +In this example the property **recipe.c.o.pattern** will be set to **/tools/g++\_arm_none_eabi/bin/arm-none-eabi-gcc**, +which is the composition of the properties **compiler.path** and **compiler.c.cmd**. #### Comments @@ -65,10 +65,9 @@ We can specify an OS-specific value for a property. For example the following fi tools.bossac.cmd=bossac tools.bossac.cmd.windows=bossac.exe -will set the property **tools.bossac.cmd** to the value **bossac** on Linux and Mac OS and **bossac.exe** on Windows. -Suffixes -[supported](https://github.com/arduino/Arduino/blob/1.8.12/arduino-core/src/processing/app/helpers/PreferencesMap.java#L110-L112) -are `.linux`, `.windows` and `.macosx`. +will set the property **tools.bossac.cmd** to the value **bossac** on Linux and macOS and **bossac.exe** on Windows. +[Supported](https://github.com/arduino/Arduino/blob/1.8.12/arduino-core/src/processing/app/helpers/PreferencesMap.java#L110-L112) +suffixes are `.linux`, `.windows` and `.macosx`. #### Global Predefined properties @@ -289,8 +288,8 @@ automatically generated properties: #### Recipe to run the preprocessor -For detecting what libraries to include in the build, and for generating function prototypes, (just) the preprocessor is -run. For this, the **recipe.preproc.macros** recipe exists. This recipe must run the preprocessor on a given source +For detecting which libraries to include in the build, and for generating function prototypes, (just) the preprocessor +is run. For this, the **recipe.preproc.macros** recipe exists. This recipe must run the preprocessor on a given source file, writing the preprocessed output to a given output file, and generate (only) preprocessor errors on standard output. This preprocessor run should happen with the same defines and other preprocessor-influencing-options as for normally compiling the source files. @@ -336,7 +335,8 @@ available hooks: - `recipe.hooks.savehex.presavehex.NUMBER.pattern` (called before savehex recipe execution) - `recipe.hooks.savehex.postsavehex.NUMBER.pattern` (called after savehex recipe execution) -Example: you want to execute 2 commands before sketch compilation and 1 after linking. You'll add to your platform.txt +Example: you want to execute two commands before sketch compilation and one after linking. You'll add to your +platform.txt: ``` recipe.hooks.sketch.prebuild.1.pattern=echo sketch compilation started at @@ -369,11 +369,11 @@ placed in the same folder as the platform.txt it supplements. ## boards.txt -This file contains definitions and meta-data for the boards supported. Every board must be referred through its short -name, the board ID. The settings for a board are defined through a set of properties with keys having the board ID as -prefix. +This file contains definitions and metadata for the boards supported by the platform. Boards are referenced by their +short name, the board ID. The settings for a board are defined through a set of properties with keys having the board ID +as prefix. -For example the board ID chosen for the Arduino Uno board is "uno". An extract of the Uno board configuration in +For example, the board ID chosen for the Arduino Uno board is "uno". An extract of the Uno board configuration in boards.txt looks like: [......] @@ -390,9 +390,9 @@ Note that all the relevant keys start with the board ID **uno.xxxxx**. The **uno.name** property contains the human-friendly name of the board. This is shown in the Board menu of the IDEs, the "Board Name" field of Arduino CLI's text output, or the "name" key of Arduino CLI's JSON output. -The **uno.build.board** property is used to set a compile-time variable **ARDUINO\_{build.board}** to allow use of +The **uno.build.board** property is used to set a compile-time macro **ARDUINO\_{build.board}** to allow use of conditional code between `#ifdef`s. If not defined, a **build.board** value is automatically generated and the Arduino -development software outputs a warning. In this case the variable defined at compile time will be `ARDUINO_AVR_UNO`. +development software outputs a warning. In this case the macro defined at compile time will be `ARDUINO_AVR_UNO`. The other properties will override the corresponding global properties when the user selects the board. These properties will be globally available, in other configuration files too, without the board ID prefix: @@ -421,7 +421,7 @@ example the following could be a valid platform layout: - `hardware/arduino/avr/cores/`: Cores folder for "avr" architecture, package "arduino" - `hardware/arduino/avr/cores/arduino`: the Arduino Core -- `hardware/arduino/avr/cores/rtos`: an hypothetical RTOS Core +- `hardware/arduino/avr/cores/rtos`: a hypothetical RTOS Core The board's property **build.core** is used to find the core that must be compiled and linked when the board is selected. For example if a board needs the Arduino core the **build.core** variable should be set to: @@ -448,9 +448,9 @@ See the [arduino/ArduinoCore-API repository](https://github.com/arduino/ArduinoC ### Core Variants -Sometimes a board needs some tweaking on default core configuration (different pin mapping is a typical example). A core -variant folder is an additional folder that is compiled together with the core and allows to easily add specific -configurations. +Sometimes a board needs some tweaking on the default core configuration (different pin mapping is a typical example). A +core variant folder is an additional folder that is compiled together with the core and allows platform developers to +easily add specific configurations. Variants must be placed inside the **variants** folder in the current architecture. For example, Arduino AVR Boards uses: @@ -576,9 +576,9 @@ variables. It is possible for the user to enable verbosity from the Preferences panel of the IDEs or Arduino CLI's `--verbose` flag. This preference is transferred to the command line using the **ACTION.verbose** property (where ACTION is the -action we are considering).
When the verbose mode is enabled the **tools.TOOL_ID.ACTION.params.verbose** property is -copied into **ACTION.verbose**. When the verbose mode is disabled, the **tools.TOOL_ID.ACTION.params.quiet** property is -copied into **ACTION.verbose**. Confused? Maybe an example will clear things: +action we are considering).
When the verbose mode is enabled, the **tools.TOOL_ID.ACTION.params.verbose** property +is copied into **ACTION.verbose**. When the verbose mode is disabled, the **tools.TOOL_ID.ACTION.params.quiet** property +is copied into **ACTION.verbose**. Confused? Maybe an example will make things clear: tools.avrdude.upload.params.verbose=-v -v -v -v tools.avrdude.upload.params.quiet=-q -q @@ -605,7 +605,7 @@ program to the Arduino board. The **upload.tool** property determines the tool t leonardo.upload.tool=avrdude [......] -Also other upload parameters can be defined together, for example in the Arduino AVR Boards boards.txt we have: +Other upload parameters can also be defined for the board. For example, in the Arduino AVR Boards boards.txt we have: [.....] uno.name=Arduino Uno @@ -663,7 +663,7 @@ starts the sketch, which then reconnects to USB. Because of these reconnections, will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on these boards interprets a bitrate of 1200 bps as a signal the bootloader should be started. -To let the Arduino development software perform these steps, two board parameters can be set: +To let the Arduino development software perform these steps, two board properties can be set to `true`: - `use_1200bps_touch` causes the selected serial port to be briefly opened at 1200 bps (8N1) before starting the upload. - `wait_for_upload_port` causes the upload procedure to wait for the serial port to (re)appear before and after the @@ -731,8 +731,8 @@ automatically generated properties: ## Custom board options It can sometimes be useful to provide user selectable configuration options for a specific board. For example, a board -could be provided in two or more variants with different CPUs, or may have different crystal speed based on the board -model, and so on... +could be provided in two or more variants with different microcontrollers, or may have different crystal speed based on +the board model, and so on... When using Arduino CLI, the option can be selected via the FQBN. @@ -741,8 +741,8 @@ In the Arduino IDE the options add extra menu items under the "Tools" menu. In Arduino Web Editor, the options are displayed in the "Flavours" menu. Let's see an example of how a custom option is implemented. The board used in the example is the Arduino Duemilanove. -This board was produced in two models, one with an ATmega168 CPU and another with an ATmega328P.
We are going then -to define a custom option, using the "cpu" MENU_ID, that allows the user to choose between the two different +This board was produced in two models, one with an ATmega168 microcontroller and another with an ATmega328P.
We are +going then to define a custom option, using the "cpu" MENU_ID, that allows the user to choose between the two different microcontrollers. We must first define a set of **menu.MENU_ID=Text** properties. Text is what is displayed on the GUI for every custom @@ -792,7 +792,7 @@ GUI.
Finally, the specific configuration for each option value: [.....] Note that when the user selects an option value, all the "sub properties" of that value are copied in the global -configuration. For example when the user selects "ATmega168" from the "Processor" menu, or uses the FQBN +configuration. For example, when the user selects "ATmega168" from the "Processor" menu, or uses the FQBN `arduino:avr:duemilanove:cpu=atmega168` with Arduino CLI, the configuration under atmega168 is made available globally: duemilanove.menu.cpu.atmega168.upload.maximum_size => upload.maximum_size @@ -825,8 +825,8 @@ The platform.txt settings are inherited from the referenced core platform, thus platform.txt unless there are some specific properties that need to be overridden. The [bundled libraries](#platform-bundled-libraries) from the referenced platform are used, thus there is no need for -the referencing platform to bundle those libraries. If libraries are provided the list of available libraries are the -sum of the 2 libraries where the referencing platform has priority over the referenced platform. +the referencing platform to bundle those libraries. If libraries are provided, the list of available libraries is the +sum of the two libraries, where the referencing platform has priority over the referenced platform. ### Variant reference @@ -860,10 +860,10 @@ can use data from up to four different platforms. To keep this clear, the follow - The "variant platform" is the platform that contains the variant to be used. - The "tool platform" is the platform that contains the tool used for the current operation. -In the most common case, without any references, all of these will refer to the same platform. +In the most common case: a board platform without any references, all of these will refer to the same platform. Note that the above terminology is not in widespread use, but was invented for clarity within this document. In the -actual arduino-cli code, the "board platform" is called `targetPlatform`, the "core platform" is called +actual Arduino Cli code, the "board platform" is called `targetPlatform`, the "core platform" is called `actualPlatform`, the others are pretty much nameless. ## boards.local.txt diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index 998507054e3..f7d77f3735d 100644 --- a/docs/sketch-build-process.md +++ b/docs/sketch-build-process.md @@ -19,12 +19,12 @@ The Arduino development software performs a few transformations to your sketch b compiler: - All .ino and .pde files in the sketch folder (shown in the Arduino IDE as tabs with no extension) are concatenated - together, starting with the file that matches the folder name followed by the others in alphabetical order, and the - .cpp extension is added to the filename. + together, starting with the file that matches the folder name followed by the others in alphabetical order. The .cpp + filename extension is then added to the resulting file. - If not already present, `#include ` is added to the sketch. This header file (found in the core folder for the currently selected board) includes all the definitions needed for the standard Arduino core. - Prototypes are generated for all function definitions in .ino/.pde files that don't already have prototypes. In some - rare cases prototype generation may fail for some functions. To work around this, you can provide your own prototypes + rare cases, prototype generation may fail for some functions. To work around this, you can provide your own prototypes for these functions. - `#line` directives are added to make warning or error messages reflect the original sketch layout. diff --git a/docs/sketch-specification.md b/docs/sketch-specification.md index d5a2f05dd54..3742c7f0228 100644 --- a/docs/sketch-specification.md +++ b/docs/sketch-specification.md @@ -14,7 +14,7 @@ what groups those files into a single program. The sketch root folder name must start with a basic letter (`A`-`Z` or `a`-`z`) or number (`0`-`9`), followed by basic letters, numbers, spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). The maximum length is 63 characters. -Support for sketch folder name starting with a number was added in Arduino IDE 1.8.4. +Support for sketch folder names starting with a number was added in Arduino IDE 1.8.4. ### Primary sketch file @@ -79,9 +79,9 @@ Editor, while only one version of each library may be installed when using the o Arduino Web Editor has a ["Secret tab" feature](https://create.arduino.cc/projecthub/Arduino_Genuino/store-your-sensitive-data-safely-when-sharing-a-sketch-e7d0f0) -that makes it easy to share sketches without accidentally exposing sensitive data (e.g., password, token). The Arduino -Web Editor automatically generates macros for any identifier in the sketch which starts with `SECRET_`and contains all -uppercase characters. +that makes it easy to share sketches without accidentally exposing sensitive data (e.g., passwords or tokens). The +Arduino Web Editor automatically generates macros for any identifier in the sketch which starts with `SECRET_` and +contains all uppercase characters. When you download a sketch from Arduino Web Editor that contains a Secret tab, the empty `#define` directives for the secrets are in a file named arduino_secrets.h, with an `#include` directive to that file at the top of the primary diff --git a/rpc/commands/board.pb.go b/rpc/commands/board.pb.go index 865d1f3989d..0d59ac0cd1d 100644 --- a/rpc/commands/board.pb.go +++ b/rpc/commands/board.pb.go @@ -73,7 +73,7 @@ func (m *BoardDetailsReq) GetFqbn() string { type BoardDetailsResp struct { // The fully qualified board name of the board. Fqbn string `protobuf:"bytes,1,opt,name=fqbn,proto3" json:"fqbn,omitempty"` - // Name used to identify the board to humans (e.g., Arduino/Genuino Uno). + // Name used to identify the board to humans (e.g., Arduino Uno). Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"` // Installed version of the board's platform. Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"` diff --git a/rpc/commands/board.proto b/rpc/commands/board.proto index 1d3f5e1f57e..b7a198f8043 100644 --- a/rpc/commands/board.proto +++ b/rpc/commands/board.proto @@ -32,7 +32,7 @@ message BoardDetailsReq { message BoardDetailsResp { // The fully qualified board name of the board. string fqbn = 1; - // Name used to identify the board to humans (e.g., Arduino/Genuino Uno). + // Name used to identify the board to humans (e.g., Arduino Uno). string name = 2; // Installed version of the board's platform. string version = 3; diff --git a/rpc/monitor/monitor.proto b/rpc/monitor/monitor.proto index a0bb4f112f7..c0ce95bbd3d 100644 --- a/rpc/monitor/monitor.proto +++ b/rpc/monitor/monitor.proto @@ -21,7 +21,7 @@ option go_package = "github.com/arduino/arduino-cli/rpc/monitor"; import "google/protobuf/struct.proto"; -// Service that abstract a Monitor usage +// Service that abstracts a Monitor usage service Monitor { // Open a bidirectional monitor stream. This can be used to implement // something similar to the Arduino IDE's Serial Monitor. From 14a66ad4c98d7933f22418d4a4d53a84d54a09d8 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 19 Aug 2020 05:14:46 -0700 Subject: [PATCH 2/3] Improve formatting of documentation --- docs/package_index_json-specification.md | 4 ++-- docs/platform-specification.md | 23 ++++++++++++++--------- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/package_index_json-specification.md b/docs/package_index_json-specification.md index 3b9937d8067..178f32bafbb 100644 --- a/docs/package_index_json-specification.md +++ b/docs/package_index_json-specification.md @@ -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.
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: @@ -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 diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 18dfcd1446c..ebb654868ac 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -1,6 +1,8 @@ This is the Arduino platform specification, for use with Arduino development software starting from the Arduino IDE -1.5.x series.
Platforms add support for new boards to the Arduino development software. They are installable either -via [Boards Manager](package_index_json-specification.md) or manual installation to the _hardware_ folder of Arduino's +1.5.x series. + +Platforms add support for new boards to the Arduino development software. They are installable either via +[Boards Manager](package_index_json-specification.md) or manual installation to the _hardware_ folder of Arduino's sketchbook folder (AKA "user directory").
A platform may consist of as little as a single configuration file. ## Hardware Folders structure @@ -240,8 +242,9 @@ files a `.hex` and a `.eep`, so we made two recipes like: recipe.objcopy.eep.pattern=[.....] recipe.objcopy.hex.pattern=[.....] -There are no specific properties set by the Arduino development software here. A full example for the AVR platform can -be: +There are no specific properties set by the Arduino development software here. + +A full example for the AVR platform can be: ## Create eeprom recipe.objcopy.eep.pattern="{compiler.path}{compiler.objcopy.cmd}" {compiler.objcopy.eep.flags} "{build.path}/{build.project_name}.elf" "{build.path}/{build.project_name}.eep" @@ -596,8 +599,10 @@ If the user didn't enable verbose mode, then **{upload.params.quiet}** is used i The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar or uses [`arduino-cli upload`](commands/arduino-cli_upload.md). Arduino uses the term "upload" for the process of transferring a -program to the Arduino board. The **upload.tool** property determines the tool to be used for upload. A specific -**upload.tool** property should be defined for every board in boards.txt: +program to the Arduino board. + +The **upload.tool** property determines the tool to be used for upload. A specific **upload.tool** property should be +defined for every board in boards.txt: [......] uno.upload.tool=avrdude @@ -745,8 +750,8 @@ This board was produced in two models, one with an ATmega168 microcontroller and going then to define a custom option, using the "cpu" MENU_ID, that allows the user to choose between the two different microcontrollers. -We must first define a set of **menu.MENU_ID=Text** properties. Text is what is displayed on the GUI for every custom -menu we are going to create and must be declared at the beginning of the boards.txt file: +We must first define a set of **menu.MENU_ID=Text** properties. **Text** is what is displayed on the GUI for every +custom menu we are going to create and must be declared at the beginning of the boards.txt file: menu.cpu=Processor [.....] @@ -774,7 +779,7 @@ Now let's define the possible values of the "cpu" option: [.....] We have defined two values: "atmega328" and "atmega168".
Note that the property keys must follow the format -**BOARD_ID.menu.MENU_ID.OPTION_ID=Text**, where Text is what is displayed under the "Processor" menu in the IDE's +**BOARD_ID.menu.MENU_ID.OPTION_ID=Text**, where **Text** is what is displayed under the "Processor" menu in the IDE's GUI.
Finally, the specific configuration for each option value: [.....] From 24307bd2f5ff4193a9e2e4aef748b995b951e09d Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 19 Aug 2020 07:40:41 -0700 Subject: [PATCH 3/3] Use correct case for Arduino CLI name in documentation Co-authored-by: Roberto Sora --- docs/platform-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index ebb654868ac..a4044164b4c 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -868,7 +868,7 @@ can use data from up to four different platforms. To keep this clear, the follow In the most common case: a board platform without any references, all of these will refer to the same platform. Note that the above terminology is not in widespread use, but was invented for clarity within this document. In the -actual Arduino Cli code, the "board platform" is called `targetPlatform`, the "core platform" is called +actual Arduino CLI code, the "board platform" is called `targetPlatform`, the "core platform" is called `actualPlatform`, the others are pretty much nameless. ## boards.local.txt