Merge pull request #279 from salewski/ads/new-proj-ex-w-edition-opt

"Creating a new project": add example using 'cargo new --edition YEAR'

Author: ehuss

src/editions/creating-a-new-project.md

@@ -1,12 +1,12 @@
 # Creating a new project
 
-When you create a new project with Cargo, it will automatically add
-configuration for the latest edition:
+A new project created with Cargo is configured to use the latest edition by
+default:
 
 ```console
-> cargo new foo
+$ cargo new foo
      Created binary (application) `foo` project
-> cat foo/Cargo.toml
+$ cat foo/Cargo.toml
 [package]
 name = "foo"
 version = "0.1.0"
@@ -15,11 +15,41 @@ edition = "2021"
 [dependencies]
 ```
 
-That `edition = "2021"` setting will configure your package to use Rust 2021.
-No more configuration needed!
+That `edition = "2021"` setting configures your package to be built using the
+Rust 2021 edition. No further configuration needed!
 
-If you'd prefer to use an older edition, you can change the value in that
-key, for example:
+You can use the `--edition <YEAR>` option of `cargo new` to create the project
+using some specific edition. For example, creating a new project to use the
+Rust 2018 edition could be done like this:
+
+```console
+$ cargo new --edition 2018 foo
+     Created binary (application) `foo` project
+$ cat foo/Cargo.toml
+[package]
+name = "foo"
+version = "0.1.0"
+edition = "2018"
+
+[dependencies]
+```
+
+Don't worry about accidentally using an invalid year for the edition; the
+`cargo new` invocation will not accept an invalid edition year value:
+
+```console
+$ cargo new --edition 2019 foo
+error: "2019" isn't a valid value for '--edition <YEAR>'
+        [possible values: 2015, 2018, 2021]
+
+        Did you mean "2018"?
+
+For more information try --help
+```
+
+You can change the value of the `edition` key by simply editing the
+`Cargo.toml` file. For example, to cause your package to be built using the
+Rust 2015 edition, you would set the key as in the following example:
 
 ```toml
 [package]
@@ -29,5 +59,3 @@ edition = "2015"
 
 [dependencies]
 ```
-
-This will build your package in Rust 2015.