From ad31aa65db65ffe54e53d75a74690525e48f34e4 Mon Sep 17 00:00:00 2001
From: "Alan D. Salewski" <ads@salewski.email>
Date: Sun, 14 Aug 2022 20:59:57 -0400
Subject: [PATCH] "Creating a new project": add example using 'cargo new
 --edition YEAR'

Also tighten-up existing prose, and use conventional '$' for
(non-root) POSIX shell prompt.

Signed-off-by: Alan D. Salewski <ads@salewski.email>
---
 src/editions/creating-a-new-project.md | 48 ++++++++++++++++++++------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/src/editions/creating-a-new-project.md b/src/editions/creating-a-new-project.md
index 319d6996..8ec71d67 100644
--- a/src/editions/creating-a-new-project.md
+++ b/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.