From bcd1062fdf1928ecd861e43d6a9f1f8878b5128a Mon Sep 17 00:00:00 2001
From: Peter Grayson <pete@jpgrayson.net>
Date: Tue, 23 Aug 2022 11:08:20 -0400
Subject: [PATCH 1/2] docs: How to override multi-line usage

Extend Command::override_usage() doc string to describe how to format
multiple usage lines to be compatible with clap's default help formatter.

Relates-to: #3413
---
 src/builder/command.rs | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/src/builder/command.rs b/src/builder/command.rs
index 7599f006..bf9d0999 100644
--- a/src/builder/command.rs
+++ b/src/builder/command.rs
@@ -1604,6 +1604,16 @@ impl Command {
     /// strings. After this setting is set, this will be *the only* usage string
     /// displayed to the user!
     ///
+    /// # Multiple usage lines
+    ///
+    /// Multiple usage lines may be present in the usage argument, but some
+    /// rules need to be followed to ensure the usage lines are formatted
+    /// correctly by the default help formatter:
+    ///
+    /// - Do not indent the first usage line.
+    /// - Indent all subsequent usage lines with four spaces.
+    /// - The last line must not end with a newline.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -1612,6 +1622,33 @@ impl Command {
     ///     .override_usage("myapp [-clDas] <some_file>")
     /// # ;
     /// ```
+    ///
+    /// Or for multiple usage lines:
+    ///
+    /// ```no_run
+    /// # use clap::{Command, Arg};
+    /// Command::new("myprog").override_usage(
+    ///     "\
+    ///     myapp -X [-a] [-b] <file>
+    ///     myapp -Y [-c] <file1> <file2>
+    ///     myapp -Z [-d|-e]"
+    /// )
+    /// # ;
+    /// ```
+    ///
+    /// or equivalently, but with different string escaping:
+    ///
+    /// ```no_run
+    /// # use clap::{Command, Arg};
+    /// Command::new("myprog")
+    ///     .override_usage(
+    ///         "myapp -X [-a] [-b] <file>\n    \
+    ///          myapp -Y [-c] <file1> <file2>\n    \
+    ///          myapp -Z [-d|-e]"
+    ///     )
+    /// # ;
+    /// ```
+    ///
     /// [`ArgMatches::usage`]: ArgMatches::usage()
     #[must_use]
     pub fn override_usage(mut self, usage: impl Into<Str>) -> Self {

From a0b1a0387743eaed1016445407053ad108227ac4 Mon Sep 17 00:00:00 2001
From: Peter Grayson <pete@jpgrayson.net>
Date: Wed, 24 Aug 2022 10:03:25 -0400
Subject: [PATCH 2/2] docs: Apply review suggestions for #4106

---
 src/builder/command.rs | 19 ++-----------------
 1 file changed, 2 insertions(+), 17 deletions(-)

diff --git a/src/builder/command.rs b/src/builder/command.rs
index bf9d0999..c7665c63 100644
--- a/src/builder/command.rs
+++ b/src/builder/command.rs
@@ -1604,10 +1604,8 @@ impl Command {
     /// strings. After this setting is set, this will be *the only* usage string
     /// displayed to the user!
     ///
-    /// # Multiple usage lines
-    ///
-    /// Multiple usage lines may be present in the usage argument, but some
-    /// rules need to be followed to ensure the usage lines are formatted
+    /// **NOTE:** Multiple usage lines may be present in the usage argument, but
+    /// some rules need to be followed to ensure the usage lines are formatted
     /// correctly by the default help formatter:
     ///
     /// - Do not indent the first usage line.
@@ -1627,19 +1625,6 @@ impl Command {
     ///
     /// ```no_run
     /// # use clap::{Command, Arg};
-    /// Command::new("myprog").override_usage(
-    ///     "\
-    ///     myapp -X [-a] [-b] <file>
-    ///     myapp -Y [-c] <file1> <file2>
-    ///     myapp -Z [-d|-e]"
-    /// )
-    /// # ;
-    /// ```
-    ///
-    /// or equivalently, but with different string escaping:
-    ///
-    /// ```no_run
-    /// # use clap::{Command, Arg};
     /// Command::new("myprog")
     ///     .override_usage(
     ///         "myapp -X [-a] [-b] <file>\n    \