From f32d640d49355f8b1f748f57f1a896bd22c0bc29 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 25 Jan 2022 09:39:11 -0600
Subject: [PATCH] docs(tutorial): Talk about required/optional subcommands

Inspired by https://github.com/clap-rs/clap/discussions/3342

Looks like we already cover this in the derive reference.
---
 .../tutorial_builder/03_04_subcommands.rs     |  4 ++-
 examples/tutorial_builder/README.md           | 36 ++++++++++---------
 examples/tutorial_derive/README.md            | 36 ++++++++++---------
 3 files changed, 43 insertions(+), 33 deletions(-)

diff --git a/examples/tutorial_builder/03_04_subcommands.rs b/examples/tutorial_builder/03_04_subcommands.rs
index f414ccd5dfb..75db59df6de 100644
--- a/examples/tutorial_builder/03_04_subcommands.rs
+++ b/examples/tutorial_builder/03_04_subcommands.rs
@@ -17,6 +17,8 @@ fn main() {
             "'myapp add' was used, name is: {:?}",
             sub_matches.value_of("NAME")
         ),
-        _ => unreachable!(),
+        _ => unreachable!(
+            "Exhausted list of subcommands and SubcommandRequiredElseHelp prevents `None`"
+        ),
     }
 }
diff --git a/examples/tutorial_builder/README.md b/examples/tutorial_builder/README.md
index 2679806f926..ff434fad538 100644
--- a/examples/tutorial_builder/README.md
+++ b/examples/tutorial_builder/README.md
@@ -272,22 +272,6 @@ subcommands.
 
 [Example:](03_04_subcommands.rs)
 ```console
-$ 03_04_subcommands
-? failed
-clap [..]
-A simple to use, efficient, and full-featured Command Line Argument Parser
-
-USAGE:
-    03_04_subcommands[EXE] <SUBCOMMAND>
-
-OPTIONS:
-    -h, --help       Print help information
-    -V, --version    Print version information
-
-SUBCOMMANDS:
-    add     Adds files to myapp
-    help    Print this message or the help of the given subcommand(s)
-
 $ 03_04_subcommands help
 clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
@@ -322,6 +306,26 @@ $ 03_04_subcommands add bob
 
 ```
 
+Because we set `AppSettings::SubcommandRequiredElseHelp`:
+```console
+$ 03_04_subcommands
+? failed
+clap [..]
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+USAGE:
+    03_04_subcommands[EXE] <SUBCOMMAND>
+
+OPTIONS:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
+SUBCOMMANDS:
+    add     Adds files to myapp
+    help    Print this message or the help of the given subcommand(s)
+
+```
+
 Because we set `AppSettings::PropagateVersion`:
 ```console
 $ 03_04_subcommands --version
diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md
index 14e627fae40..1d2b5f1f2b3 100644
--- a/examples/tutorial_derive/README.md
+++ b/examples/tutorial_derive/README.md
@@ -274,22 +274,6 @@ subcommands.
 
 [Example:](03_04_subcommands.rs)
 ```console
-$ 03_04_subcommands_derive
-? failed
-clap [..]
-A simple to use, efficient, and full-featured Command Line Argument Parser
-
-USAGE:
-    03_04_subcommands_derive[EXE] <SUBCOMMAND>
-
-OPTIONS:
-    -h, --help       Print help information
-    -V, --version    Print version information
-
-SUBCOMMANDS:
-    add     Adds files to myapp
-    help    Print this message or the help of the given subcommand(s)
-
 $ 03_04_subcommands_derive help
 clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
@@ -324,6 +308,26 @@ $ 03_04_subcommands_derive add bob
 
 ```
 
+Because we used `command: Commands` instead of `command: Option<Commands>`:
+```console
+$ 03_04_subcommands_derive
+? failed
+clap [..]
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+USAGE:
+    03_04_subcommands_derive[EXE] <SUBCOMMAND>
+
+OPTIONS:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
+SUBCOMMANDS:
+    add     Adds files to myapp
+    help    Print this message or the help of the given subcommand(s)
+
+```
+
 Because we set `AppSettings::PropagateVersion`:
 ```console
 $ 03_04_subcommands_derive --version