Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 19, 2020
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
31f4814
Restructure paragraph re: standardizing architecture names
per1234 Aug 18, 2020
a8b77cc
Improve wording of documentation
per1234 Aug 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cli/compile/compile.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/library-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions docs/package_index_json-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)

Expand Down
15 changes: 8 additions & 7 deletions docs/platform-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions docs/sketch-build-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down