From c6155f62d549ac08f6ff6faecd3ec1a9327dbf17 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Wed, 24 Aug 2022 10:24:15 -0500
Subject: [PATCH 01/22] feat: Open the door for user styling in the future

This added about 10 KiB to the `.text` which I cannot explain why
---
 clap_complete/src/shells/elvish.rs     |  5 +-
 clap_complete/src/shells/fish.rs       |  8 +--
 clap_complete/src/shells/powershell.rs |  5 +-
 clap_complete/src/shells/zsh.rs        | 12 +++--
 clap_complete_fig/src/fig.rs           | 10 ++--
 clap_mangen/src/render.rs              |  8 +--
 src/builder/arg.rs                     | 19 +++----
 src/builder/command.rs                 | 72 +++++++++++++-------------
 src/builder/debug_asserts.rs           |  4 +-
 src/builder/possible_value.rs          | 13 ++---
 src/builder/resettable.rs              | 16 ++++++
 src/builder/styled_str.rs              | 43 ++++++++++++++-
 src/output/help.rs                     | 32 ++++++++----
 src/output/usage.rs                    |  2 +-
 tests/builder/tests.rs                 | 12 ++++-
 tests/derive/doc_comments_help.rs      |  5 +-
 tests/derive/flags.rs                  | 12 ++++-
 tests/macros.rs                        | 48 ++++++++++-------
 18 files changed, 215 insertions(+), 111 deletions(-)

diff --git a/clap_complete/src/shells/elvish.rs b/clap_complete/src/shells/elvish.rs
index 83406776505..d2a267f6f79 100644
--- a/clap_complete/src/shells/elvish.rs
+++ b/clap_complete/src/shells/elvish.rs
@@ -1,5 +1,6 @@
 use std::io::Write;
 
+use clap::builder::StyledStr;
 use clap::*;
 
 use crate::generator::{utils, Generator};
@@ -59,9 +60,9 @@ fn escape_string(string: &str) -> String {
     string.replace('\'', "''")
 }
 
-fn get_tooltip<T: ToString>(help: Option<&str>, data: T) -> String {
+fn get_tooltip<T: ToString>(help: Option<&StyledStr>, data: T) -> String {
     match help {
-        Some(help) => escape_string(help),
+        Some(help) => escape_string(&help.to_string()),
         _ => data.to_string(),
     }
 }
diff --git a/clap_complete/src/shells/fish.rs b/clap_complete/src/shells/fish.rs
index 2550a22989b..b37cda89614 100644
--- a/clap_complete/src/shells/fish.rs
+++ b/clap_complete/src/shells/fish.rs
@@ -93,7 +93,7 @@ fn gen_fish_inner(
         }
 
         if let Some(data) = option.get_help() {
-            template.push_str(format!(" -d '{}'", escape_string(data)).as_str());
+            template.push_str(format!(" -d '{}'", escape_string(&data.to_string())).as_str());
         }
 
         template.push_str(value_completion(option).as_str());
@@ -118,7 +118,7 @@ fn gen_fish_inner(
         }
 
         if let Some(data) = flag.get_help() {
-            template.push_str(format!(" -d '{}'", escape_string(data)).as_str());
+            template.push_str(format!(" -d '{}'", escape_string(&data.to_string())).as_str());
         }
 
         buffer.push_str(template.as_str());
@@ -132,7 +132,7 @@ fn gen_fish_inner(
         template.push_str(format!(" -a \"{}\"", &subcommand.get_name()).as_str());
 
         if let Some(data) = subcommand.get_about() {
-            template.push_str(format!(" -d '{}'", escape_string(data)).as_str())
+            template.push_str(format!(" -d '{}'", escape_string(&data.to_string())).as_str())
         }
 
         buffer.push_str(template.as_str());
@@ -164,7 +164,7 @@ fn value_completion(option: &Arg) -> String {
                     Some(format!(
                         "{}\t{}",
                         escape_string(value.get_name()).as_str(),
-                        escape_string(value.get_help().unwrap_or_default()).as_str()
+                        escape_string(&value.get_help().unwrap_or_default().to_string())
                     ))
                 })
                 .collect::<Vec<_>>()
diff --git a/clap_complete/src/shells/powershell.rs b/clap_complete/src/shells/powershell.rs
index ec12bd28e3c..ae7e4a750cf 100644
--- a/clap_complete/src/shells/powershell.rs
+++ b/clap_complete/src/shells/powershell.rs
@@ -1,5 +1,6 @@
 use std::io::Write;
 
+use clap::builder::StyledStr;
 use clap::*;
 
 use crate::generator::{utils, Generator};
@@ -64,9 +65,9 @@ fn escape_string(string: &str) -> String {
     string.replace('\'', "''")
 }
 
-fn get_tooltip<T: ToString>(help: Option<&str>, data: T) -> String {
+fn get_tooltip<T: ToString>(help: Option<&StyledStr>, data: T) -> String {
     match help {
-        Some(help) => escape_string(help),
+        Some(help) => escape_string(&help.to_string()),
         _ => data.to_string(),
     }
 }
diff --git a/clap_complete/src/shells/zsh.rs b/clap_complete/src/shells/zsh.rs
index 8aa032a9549..894b5f1487f 100644
--- a/clap_complete/src/shells/zsh.rs
+++ b/clap_complete/src/shells/zsh.rs
@@ -153,7 +153,7 @@ fn subcommands_of(p: &Command) -> String {
         let text = format!(
             "'{name}:{help}' \\",
             name = name,
-            help = escape_help(subcommand.get_about().unwrap_or_default())
+            help = escape_help(&subcommand.get_about().unwrap_or_default().to_string())
         );
 
         if !text.is_empty() {
@@ -372,7 +372,8 @@ fn value_completion(arg: &Arg) -> Option<String> {
                             Some(format!(
                                 r#"{name}\:"{tooltip}""#,
                                 name = escape_value(value.get_name()),
-                                tooltip = value.get_help().map(escape_help).unwrap_or_default()
+                                tooltip =
+                                    escape_help(&value.get_help().unwrap_or_default().to_string()),
                             ))
                         }
                     })
@@ -445,7 +446,7 @@ fn write_opts_of(p: &Command, p_global: Option<&Command>) -> String {
     for o in p.get_opts() {
         debug!("write_opts_of:iter: o={}", o.get_id());
 
-        let help = o.get_help().map(escape_help).unwrap_or_default();
+        let help = escape_help(&o.get_help().unwrap_or_default().to_string());
         let conflicts = arg_conflicts(p, o, p_global);
 
         let multiple = "*";
@@ -541,7 +542,7 @@ fn write_flags_of(p: &Command, p_global: Option<&Command>) -> String {
     for f in utils::flags(p) {
         debug!("write_flags_of:iter: f={}", f.get_id());
 
-        let help = f.get_help().map(escape_help).unwrap_or_default();
+        let help = escape_help(&f.get_help().unwrap_or_default().to_string());
         let conflicts = arg_conflicts(p, &f, p_global);
 
         let multiple = "*";
@@ -634,7 +635,8 @@ fn write_positionals_of(p: &Command) -> String {
             name = arg.get_id(),
             help = arg
                 .get_help()
-                .map_or("".to_owned(), |v| " -- ".to_owned() + v)
+                .map(|s| s.to_string())
+                .map_or("".to_owned(), |v| " -- ".to_owned() + &v)
                 .replace('[', "\\[")
                 .replace(']', "\\]")
                 .replace('\'', "'\\''")
diff --git a/clap_complete_fig/src/fig.rs b/clap_complete_fig/src/fig.rs
index e9d9186d13a..135bbd337f4 100644
--- a/clap_complete_fig/src/fig.rs
+++ b/clap_complete_fig/src/fig.rs
@@ -28,7 +28,7 @@ impl Generator for Fig {
         write!(
             &mut buffer,
             "  description: \"{}\",\n",
-            escape_string(cmd.get_about().unwrap_or_default())
+            escape_string(&cmd.get_about().unwrap_or_default().to_string())
         )
         .unwrap();
 
@@ -101,7 +101,7 @@ fn gen_fig_inner(
                     buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(data),
+                    escape_string(&data.to_string()),
                     indent = indent + 4
                 )
                 .unwrap();
@@ -205,7 +205,7 @@ fn gen_options(cmd: &Command, indent: usize) -> String {
                     &mut buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(data),
+                    escape_string(&data.to_string()),
                     indent = indent + 4
                 )
                 .unwrap();
@@ -314,7 +314,7 @@ fn gen_options(cmd: &Command, indent: usize) -> String {
                     &mut buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(data).as_str(),
+                    escape_string(&data.to_string()).as_str(),
                     indent = indent + 4
                 )
                 .unwrap();
@@ -426,7 +426,7 @@ fn gen_args(arg: &Arg, indent: usize) -> String {
                     &mut buffer,
                     "{:indent$}description: \"{}\",\n",
                     "",
-                    escape_string(help),
+                    escape_string(&help.to_string()),
                     indent = indent + 6
                 )
                 .unwrap();
diff --git a/clap_mangen/src/render.rs b/clap_mangen/src/render.rs
index 0548cef42e0..8a378fd5836 100644
--- a/clap_mangen/src/render.rs
+++ b/clap_mangen/src/render.rs
@@ -17,7 +17,7 @@ pub(crate) fn about(roff: &mut Roff, cmd: &clap::Command) {
 
 pub(crate) fn description(roff: &mut Roff, cmd: &clap::Command) {
     if let Some(about) = cmd.get_long_about().or_else(|| cmd.get_about()) {
-        for line in about.lines() {
+        for line in about.to_string().lines() {
             if line.trim().is_empty() {
                 roff.control("PP", []);
             } else {
@@ -110,7 +110,7 @@ pub(crate) fn options(roff: &mut Roff, cmd: &clap::Command) {
         let mut arg_help_written = false;
         if let Some(help) = opt.get_long_help().or_else(|| opt.get_help()) {
             arg_help_written = true;
-            body.push(roman(help));
+            body.push(roman(help.to_string()));
         }
 
         roff.control("TP", []);
@@ -224,7 +224,7 @@ pub(crate) fn subcommands(roff: &mut Roff, cmd: &clap::Command, section: &str) {
         roff.text([roman(&name)]);
 
         if let Some(about) = sub.get_about().or_else(|| sub.get_long_about()) {
-            for line in about.lines() {
+            for line in about.to_string().lines() {
                 roff.text([roman(line)]);
             }
         }
@@ -242,7 +242,7 @@ pub(crate) fn version(cmd: &clap::Command) -> String {
 
 pub(crate) fn after_help(roff: &mut Roff, cmd: &clap::Command) {
     if let Some(about) = cmd.get_after_long_help().or_else(|| cmd.get_after_help()) {
-        for line in about.lines() {
+        for line in about.to_string().lines() {
             roff.text([roman(line)]);
         }
     }
diff --git a/src/builder/arg.rs b/src/builder/arg.rs
index 7fbd0b320ef..3879373ab55 100644
--- a/src/builder/arg.rs
+++ b/src/builder/arg.rs
@@ -17,6 +17,7 @@ use crate::builder::IntoResettable;
 use crate::builder::OsStr;
 use crate::builder::PossibleValue;
 use crate::builder::Str;
+use crate::builder::StyledStr;
 use crate::builder::ValueRange;
 use crate::ArgAction;
 use crate::Id;
@@ -54,8 +55,8 @@ use crate::INTERNAL_ERROR_MSG;
 #[derive(Default, Clone)]
 pub struct Arg {
     pub(crate) id: Id,
-    pub(crate) help: Option<Str>,
-    pub(crate) long_help: Option<Str>,
+    pub(crate) help: Option<StyledStr>,
+    pub(crate) long_help: Option<StyledStr>,
     pub(crate) action: Option<ArgAction>,
     pub(crate) value_parser: Option<super::ValueParser>,
     pub(crate) blacklist: Vec<Id>,
@@ -1900,7 +1901,7 @@ impl Arg {
     /// [`Arg::long_help`]: Arg::long_help()
     #[inline]
     #[must_use]
-    pub fn help(mut self, h: impl IntoResettable<Str>) -> Self {
+    pub fn help(mut self, h: impl IntoResettable<StyledStr>) -> Self {
         self.help = h.into_resettable().into_option();
         self
     }
@@ -1962,7 +1963,7 @@ impl Arg {
     /// [`Arg::help`]: Arg::help()
     #[inline]
     #[must_use]
-    pub fn long_help(mut self, h: impl IntoResettable<Str>) -> Self {
+    pub fn long_help(mut self, h: impl IntoResettable<StyledStr>) -> Self {
         self.long_help = h.into_resettable().into_option();
         self
     }
@@ -3539,8 +3540,8 @@ impl Arg {
 
     /// Get the help specified for this argument, if any
     #[inline]
-    pub fn get_help(&self) -> Option<&str> {
-        self.help.as_deref()
+    pub fn get_help(&self) -> Option<&StyledStr> {
+        self.help.as_ref()
     }
 
     /// Get the long help specified for this argument, if any
@@ -3550,12 +3551,12 @@ impl Arg {
     /// ```rust
     /// # use clap::Arg;
     /// let arg = Arg::new("foo").long_help("long help");
-    /// assert_eq!(Some("long help"), arg.get_long_help());
+    /// assert_eq!(Some("long help".to_owned()), arg.get_long_help().map(|s| s.to_string()));
     /// ```
     ///
     #[inline]
-    pub fn get_long_help(&self) -> Option<&str> {
-        self.long_help.as_deref()
+    pub fn get_long_help(&self) -> Option<&StyledStr> {
+        self.long_help.as_ref()
     }
 
     /// Get the help heading specified for this argument, if any
diff --git a/src/builder/command.rs b/src/builder/command.rs
index 461cc8974ad..163d1687e6b 100644
--- a/src/builder/command.rs
+++ b/src/builder/command.rs
@@ -75,22 +75,22 @@ pub struct Command {
     author: Option<Str>,
     version: Option<Str>,
     long_version: Option<Str>,
-    about: Option<Str>,
-    long_about: Option<Str>,
-    before_help: Option<Str>,
-    before_long_help: Option<Str>,
-    after_help: Option<Str>,
-    after_long_help: Option<Str>,
+    about: Option<StyledStr>,
+    long_about: Option<StyledStr>,
+    before_help: Option<StyledStr>,
+    before_long_help: Option<StyledStr>,
+    after_help: Option<StyledStr>,
+    after_long_help: Option<StyledStr>,
     aliases: Vec<(Str, bool)>,             // (name, visible)
     short_flag_aliases: Vec<(char, bool)>, // (name, visible)
     long_flag_aliases: Vec<(Str, bool)>,   // (name, visible)
-    usage_str: Option<Str>,
+    usage_str: Option<StyledStr>,
     usage_name: Option<String>,
-    help_str: Option<Str>,
+    help_str: Option<StyledStr>,
     disp_ord: Option<usize>,
     term_w: Option<usize>,
     max_w: Option<usize>,
-    template: Option<Str>,
+    template: Option<StyledStr>,
     settings: AppFlags,
     g_settings: AppFlags,
     args: MKeyMap,
@@ -1442,7 +1442,7 @@ impl Command {
     /// # ;
     /// ```
     #[must_use]
-    pub fn about(mut self, about: impl IntoResettable<Str>) -> Self {
+    pub fn about(mut self, about: impl IntoResettable<StyledStr>) -> Self {
         self.about = about.into_resettable().into_option();
         self
     }
@@ -1467,7 +1467,7 @@ impl Command {
     /// ```
     /// [`Command::about`]: Command::about()
     #[must_use]
-    pub fn long_about(mut self, long_about: impl IntoResettable<Str>) -> Self {
+    pub fn long_about(mut self, long_about: impl IntoResettable<StyledStr>) -> Self {
         self.long_about = long_about.into_resettable().into_option();
         self
     }
@@ -1489,7 +1489,7 @@ impl Command {
     /// ```
     ///
     #[must_use]
-    pub fn after_help(mut self, help: impl Into<Str>) -> Self {
+    pub fn after_help(mut self, help: impl Into<StyledStr>) -> Self {
         self.after_help = Some(help.into());
         self
     }
@@ -1511,7 +1511,7 @@ impl Command {
     /// # ;
     /// ```
     #[must_use]
-    pub fn after_long_help(mut self, help: impl Into<Str>) -> Self {
+    pub fn after_long_help(mut self, help: impl Into<StyledStr>) -> Self {
         self.after_long_help = Some(help.into());
         self
     }
@@ -1531,7 +1531,7 @@ impl Command {
     /// # ;
     /// ```
     #[must_use]
-    pub fn before_help(mut self, help: impl Into<Str>) -> Self {
+    pub fn before_help(mut self, help: impl Into<StyledStr>) -> Self {
         self.before_help = Some(help.into());
         self
     }
@@ -1551,7 +1551,7 @@ impl Command {
     /// # ;
     /// ```
     #[must_use]
-    pub fn before_long_help(mut self, help: impl Into<Str>) -> Self {
+    pub fn before_long_help(mut self, help: impl Into<StyledStr>) -> Self {
         self.before_long_help = Some(help.into());
         self
     }
@@ -1645,7 +1645,7 @@ impl Command {
     ///
     /// [`ArgMatches::usage`]: ArgMatches::usage()
     #[must_use]
-    pub fn override_usage(mut self, usage: impl Into<Str>) -> Self {
+    pub fn override_usage(mut self, usage: impl Into<StyledStr>) -> Self {
         self.usage_str = Some(usage.into());
         self
     }
@@ -1682,7 +1682,7 @@ impl Command {
     /// # ;
     /// ```
     #[must_use]
-    pub fn override_help(mut self, help: impl Into<Str>) -> Self {
+    pub fn override_help(mut self, help: impl Into<StyledStr>) -> Self {
         self.help_str = Some(help.into());
         self
     }
@@ -1732,7 +1732,7 @@ impl Command {
     /// [`Command::before_help`]: Command::before_help()
     /// [`Command::before_long_help`]: Command::before_long_help()
     #[must_use]
-    pub fn help_template(mut self, s: impl Into<Str>) -> Self {
+    pub fn help_template(mut self, s: impl Into<StyledStr>) -> Self {
         self.template = Some(s.into());
         self
     }
@@ -3242,16 +3242,16 @@ impl Command {
     ///
     /// [`Command::about`]: Command::about()
     #[inline]
-    pub fn get_about(&self) -> Option<&str> {
-        self.about.as_deref()
+    pub fn get_about(&self) -> Option<&StyledStr> {
+        self.about.as_ref()
     }
 
     /// Get the help message specified via [`Command::long_about`].
     ///
     /// [`Command::long_about`]: Command::long_about()
     #[inline]
-    pub fn get_long_about(&self) -> Option<&str> {
-        self.long_about.as_deref()
+    pub fn get_long_about(&self) -> Option<&StyledStr> {
+        self.long_about.as_ref()
     }
 
     /// Get the custom section heading specified via [`Command::next_help_heading`].
@@ -3364,26 +3364,26 @@ impl Command {
 
     /// Returns the help heading for listing subcommands.
     #[inline]
-    pub fn get_before_help(&self) -> Option<&str> {
-        self.before_help.as_deref()
+    pub fn get_before_help(&self) -> Option<&StyledStr> {
+        self.before_help.as_ref()
     }
 
     /// Returns the help heading for listing subcommands.
     #[inline]
-    pub fn get_before_long_help(&self) -> Option<&str> {
-        self.before_long_help.as_deref()
+    pub fn get_before_long_help(&self) -> Option<&StyledStr> {
+        self.before_long_help.as_ref()
     }
 
     /// Returns the help heading for listing subcommands.
     #[inline]
-    pub fn get_after_help(&self) -> Option<&str> {
-        self.after_help.as_deref()
+    pub fn get_after_help(&self) -> Option<&StyledStr> {
+        self.after_help.as_ref()
     }
 
     /// Returns the help heading for listing subcommands.
     #[inline]
-    pub fn get_after_long_help(&self) -> Option<&str> {
-        self.after_long_help.as_deref()
+    pub fn get_after_long_help(&self) -> Option<&StyledStr> {
+        self.after_long_help.as_ref()
     }
 
     /// Find subcommand such that its name or one of aliases equals `name`.
@@ -3667,16 +3667,16 @@ impl Command {
 
 // Internally used only
 impl Command {
-    pub(crate) fn get_override_usage(&self) -> Option<&str> {
-        self.usage_str.as_deref()
+    pub(crate) fn get_override_usage(&self) -> Option<&StyledStr> {
+        self.usage_str.as_ref()
     }
 
-    pub(crate) fn get_override_help(&self) -> Option<&str> {
-        self.help_str.as_deref()
+    pub(crate) fn get_override_help(&self) -> Option<&StyledStr> {
+        self.help_str.as_ref()
     }
 
-    pub(crate) fn get_help_template(&self) -> Option<&str> {
-        self.template.as_deref()
+    pub(crate) fn get_help_template(&self) -> Option<&StyledStr> {
+        self.template.as_ref()
     }
 
     pub(crate) fn get_term_width(&self) -> Option<usize> {
diff --git a/src/builder/debug_asserts.rs b/src/builder/debug_asserts.rs
index 140a5ad9344..afb4aa5ab3f 100644
--- a/src/builder/debug_asserts.rs
+++ b/src/builder/debug_asserts.rs
@@ -339,13 +339,13 @@ pub(crate) fn assert_app(cmd: &Command) {
 
     if let Some(help_template) = cmd.get_help_template() {
         assert!(
-            !help_template.contains("{flags}"),
+            !help_template.to_string().contains("{flags}"),
             "Command {}: {}",
                     cmd.get_name(),
             "`{flags}` template variable was removed in clap3, they are now included in `{options}`",
         );
         assert!(
-            !help_template.contains("{unified}"),
+            !help_template.to_string().contains("{unified}"),
             "Command {}: {}",
             cmd.get_name(),
             "`{unified}` template variable was removed in clap3, use `{options}` instead"
diff --git a/src/builder/possible_value.rs b/src/builder/possible_value.rs
index acf671b29f6..93f012e89d4 100644
--- a/src/builder/possible_value.rs
+++ b/src/builder/possible_value.rs
@@ -1,6 +1,7 @@
 use std::{borrow::Cow, iter};
 
 use crate::builder::Str;
+use crate::builder::StyledStr;
 use crate::util::eq_ignore_case;
 
 /// A possible value of an argument.
@@ -30,7 +31,7 @@ use crate::util::eq_ignore_case;
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct PossibleValue {
     name: Str,
-    help: Option<Str>,
+    help: Option<StyledStr>,
     aliases: Vec<Str>, // (name, visible)
     hide: bool,
 }
@@ -75,7 +76,7 @@ impl PossibleValue {
     /// ```
     #[inline]
     #[must_use]
-    pub fn help(mut self, help: impl Into<Str>) -> Self {
+    pub fn help(mut self, help: impl Into<StyledStr>) -> Self {
         self.help = Some(help.into());
         self
     }
@@ -144,16 +145,16 @@ impl PossibleValue {
 
     /// Get the help specified for this argument, if any
     #[inline]
-    pub fn get_help(&self) -> Option<&str> {
-        self.help.as_deref()
+    pub fn get_help(&self) -> Option<&StyledStr> {
+        self.help.as_ref()
     }
 
     /// Get the help specified for this argument, if any and the argument
     /// value is not hidden
     #[inline]
-    pub(crate) fn get_visible_help(&self) -> Option<&str> {
+    pub(crate) fn get_visible_help(&self) -> Option<&StyledStr> {
         if !self.hide {
-            self.help.as_deref()
+            self.get_help()
         } else {
             None
         }
diff --git a/src/builder/resettable.rs b/src/builder/resettable.rs
index e7b111d041f..158ff059407 100644
--- a/src/builder/resettable.rs
+++ b/src/builder/resettable.rs
@@ -3,6 +3,7 @@
 
 use crate::builder::OsStr;
 use crate::builder::Str;
+use crate::builder::StyledStr;
 
 /// Clearable builder value
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -43,6 +44,15 @@ pub trait IntoResettable<T> {
     fn into_resettable(self) -> Resettable<T>;
 }
 
+impl IntoResettable<StyledStr> for Option<&'static str> {
+    fn into_resettable(self) -> Resettable<StyledStr> {
+        match self {
+            Some(s) => Resettable::Value(s.into()),
+            None => Resettable::Reset,
+        }
+    }
+}
+
 impl IntoResettable<OsStr> for Option<&'static str> {
     fn into_resettable(self) -> Resettable<OsStr> {
         match self {
@@ -67,6 +77,12 @@ impl<T> IntoResettable<T> for Resettable<T> {
     }
 }
 
+impl<I: Into<StyledStr>> IntoResettable<StyledStr> for I {
+    fn into_resettable(self) -> Resettable<StyledStr> {
+        Resettable::Value(self.into())
+    }
+}
+
 impl<I: Into<OsStr>> IntoResettable<OsStr> for I {
     fn into_resettable(self) -> Resettable<OsStr> {
         Resettable::Value(self.into())
diff --git a/src/builder/styled_str.rs b/src/builder/styled_str.rs
index afe2545a3ff..d315e7e1bab 100644
--- a/src/builder/styled_str.rs
+++ b/src/builder/styled_str.rs
@@ -32,7 +32,41 @@ impl StyledStr {
     }
 
     fn stylize(&mut self, style: Option<Style>, msg: String) {
-        self.pieces.push((style, msg));
+        if !msg.is_empty() {
+            self.pieces.push((style, msg));
+        }
+    }
+
+    /// HACK: Until call sites are updated to handle formatted text, extract the unformatted
+    #[track_caller]
+    pub(crate) fn unwrap_none(&self) -> &str {
+        match self.pieces.len() {
+            0 => "",
+            1 => {
+                if self.pieces[0].0 != None {
+                    panic!("{}", crate::INTERNAL_ERROR_MSG)
+                }
+                self.pieces[0].1.as_str()
+            }
+            _ => panic!("{}", crate::INTERNAL_ERROR_MSG),
+        }
+    }
+
+    pub(crate) fn is_empty(&self) -> bool {
+        self.pieces.is_empty()
+    }
+
+    pub(crate) fn iter(&self) -> impl Iterator<Item = (Option<Style>, &str)> {
+        self.pieces.iter().map(|(s, c)| (*s, c.as_str()))
+    }
+
+    pub(crate) fn extend(
+        &mut self,
+        other: impl IntoIterator<Item = (impl Into<Option<Style>>, impl Into<String>)>,
+    ) {
+        for (style, content) in other {
+            self.stylize(style.into(), content.into());
+        }
     }
 
     #[cfg(feature = "color")]
@@ -68,6 +102,13 @@ impl StyledStr {
     }
 }
 
+impl Default for &'_ StyledStr {
+    fn default() -> Self {
+        static DEFAULT: StyledStr = StyledStr::new();
+        &DEFAULT
+    }
+}
+
 impl From<std::string::String> for StyledStr {
     fn from(name: std::string::String) -> Self {
         let mut styled = StyledStr::new();
diff --git a/src/output/help.rs b/src/output/help.rs
index 23b20ec1ad7..1d6e73b1c77 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -80,9 +80,9 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         debug!("Help::write_help");
 
         if let Some(h) = self.cmd.get_override_help() {
-            self.none(h);
+            self.extend(h);
         } else if let Some(tmpl) = self.cmd.get_help_template() {
-            self.write_templated_help(tmpl);
+            self.write_templated_help(tmpl.unwrap_none());
         } else {
             let pos = self
                 .cmd
@@ -107,6 +107,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
 
 // Methods to write Arg help.
 impl<'cmd, 'writer> Help<'cmd, 'writer> {
+    fn extend(&mut self, msg: &StyledStr) {
+        self.writer.extend(msg.iter());
+    }
+
     fn good<T: Into<String>>(&mut self, msg: T) {
         self.writer.good(msg);
     }
@@ -353,7 +357,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             self.cmd.get_before_help()
         };
         if let Some(output) = before_help {
-            self.none(text_wrapper(&output.replace("{n}", "\n"), self.term_w));
+            self.none(text_wrapper(
+                &output.unwrap_none().replace("{n}", "\n"),
+                self.term_w,
+            ));
             self.none("\n\n");
         }
     }
@@ -369,7 +376,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         };
         if let Some(output) = after_help {
             self.none("\n\n");
-            self.none(text_wrapper(&output.replace("{n}", "\n"), self.term_w));
+            self.none(text_wrapper(
+                &output.unwrap_none().replace("{n}", "\n"),
+                self.term_w,
+            ));
         }
     }
 
@@ -377,13 +387,13 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     fn help(
         &mut self,
         arg: Option<&Arg>,
-        about: &str,
+        about: &StyledStr,
         spec_vals: &str,
         next_line_help: bool,
         longest: usize,
     ) {
         debug!("Help::help");
-        let mut help = String::from(about) + spec_vals;
+        let mut help = String::from(about.unwrap_none()) + spec_vals;
         debug!("Help::help: Next Line...{:?}", next_line_help);
 
         let spaces = if next_line_help {
@@ -451,7 +461,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                     .expect("Only called with possible value");
                 let help_longest = possible_vals
                     .iter()
-                    .filter_map(|f| f.get_visible_help().map(display_width))
+                    .filter_map(|f| f.get_visible_help().map(|h| display_width(h.unwrap_none())))
                     .max()
                     .expect("Only called with possible value with help");
                 // should new line
@@ -490,7 +500,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                             usize::MAX
                         };
 
-                        let help = text_wrapper(help, avail_chars);
+                        let help = text_wrapper(help.unwrap_none(), avail_chars);
                         let mut help = help.lines();
 
                         self.none(help.next().unwrap_or_default());
@@ -522,7 +532,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         } else {
             // force_next_line
             let h = arg.get_help().unwrap_or_default();
-            let h_w = display_width(h) + display_width(spec_vals);
+            let h_w = display_width(h.unwrap_none()) + display_width(spec_vals);
             let taken = longest + 12;
             self.term_w >= taken
                 && (taken as f32 / self.term_w as f32) > 0.40
@@ -649,7 +659,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             if before_new_line {
                 self.none("\n");
             }
-            self.none(text_wrapper(output, self.term_w));
+            self.none(text_wrapper(output.unwrap_none(), self.term_w));
             if after_new_line {
                 self.none("\n");
             }
@@ -739,7 +749,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         } else {
             // force_next_line
             let h = cmd.get_about().unwrap_or_default();
-            let h_w = display_width(h) + display_width(spec_vals);
+            let h_w = display_width(h.unwrap_none()) + display_width(spec_vals);
             let taken = longest + 12;
             self.term_w >= taken
                 && (taken as f32 / self.term_w as f32) > 0.40
diff --git a/src/output/usage.rs b/src/output/usage.rs
index f1cc94bdfe1..9a7d1cbb2af 100644
--- a/src/output/usage.rs
+++ b/src/output/usage.rs
@@ -40,7 +40,7 @@ impl<'cmd> Usage<'cmd> {
     pub(crate) fn create_usage_no_title(&self, used: &[Id]) -> String {
         debug!("Usage::create_usage_no_title");
         if let Some(u) = self.cmd.get_override_usage() {
-            u.to_owned()
+            u.to_string()
         } else if used.is_empty() {
             self.create_help_usage(true)
         } else {
diff --git a/tests/builder/tests.rs b/tests/builder/tests.rs
index ea976c3ee8f..433e39ef6eb 100644
--- a/tests/builder/tests.rs
+++ b/tests/builder/tests.rs
@@ -450,7 +450,11 @@ fn mut_subcommand_with_alias_resolve() {
     let mut cmd =
         Command::new("foo").subcommand(Command::new("bar").alias("baz").about("test subcmd"));
     assert_eq!(
-        cmd.find_subcommand("baz").unwrap().get_about().unwrap(),
+        cmd.find_subcommand("baz")
+            .unwrap()
+            .get_about()
+            .unwrap()
+            .to_string(),
         "test subcmd"
     );
 
@@ -459,7 +463,11 @@ fn mut_subcommand_with_alias_resolve() {
 
     cmd = cmd.mut_subcommand(&*true_name, |subcmd| subcmd.about("modified about"));
     assert_eq!(
-        cmd.find_subcommand("baz").unwrap().get_about().unwrap(),
+        cmd.find_subcommand("baz")
+            .unwrap()
+            .get_about()
+            .unwrap()
+            .to_string(),
         "modified about"
     );
 }
diff --git a/tests/derive/doc_comments_help.rs b/tests/derive/doc_comments_help.rs
index bfe152a6102..d894614bb92 100644
--- a/tests/derive/doc_comments_help.rs
+++ b/tests/derive/doc_comments_help.rs
@@ -233,7 +233,10 @@ fn doc_comment_about_handles_both_abouts() {
     }
 
     let cmd = Opts::command();
-    assert_eq!(cmd.get_about(), Some("Opts doc comment summary"));
+    assert_eq!(
+        cmd.get_about().map(|s| s.to_string()),
+        Some("Opts doc comment summary".to_owned())
+    );
     // clap will fallback to `about` on `None`.  The main care about is not providing a `Sub` doc
     // comment.
     assert_eq!(cmd.get_long_about(), None);
diff --git a/tests/derive/flags.rs b/tests/derive/flags.rs
index dd15823b6fb..1e19623fcab 100644
--- a/tests/derive/flags.rs
+++ b/tests/derive/flags.rs
@@ -94,7 +94,11 @@ fn inferred_help() {
     let mut cmd = Opt::command();
     cmd.build();
     let arg = cmd.get_arguments().find(|a| a.get_id() == "help").unwrap();
-    assert_eq!(arg.get_help(), Some("Foo"), "Incorrect help");
+    assert_eq!(
+        arg.get_help().map(|s| s.to_string()),
+        Some("Foo".to_owned()),
+        "Incorrect help"
+    );
     assert!(matches!(arg.get_action(), clap::ArgAction::Help));
 }
 
@@ -114,7 +118,11 @@ fn inferred_version() {
         .get_arguments()
         .find(|a| a.get_id() == "version")
         .unwrap();
-    assert_eq!(arg.get_help(), Some("Foo"), "Incorrect help");
+    assert_eq!(
+        arg.get_help().map(|s| s.to_string()),
+        Some("Foo".to_owned()),
+        "Incorrect help"
+    );
     assert!(matches!(arg.get_action(), clap::ArgAction::Version));
 }
 
diff --git a/tests/macros.rs b/tests/macros.rs
index 9ea5c7cf212..be61b9bed4d 100644
--- a/tests/macros.rs
+++ b/tests/macros.rs
@@ -46,7 +46,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::SetTrue));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -'b');
         assert_eq!(arg.get_id(), "foo");
@@ -54,7 +54,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::SetTrue));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -b ...);
         assert_eq!(arg.get_id(), "foo");
@@ -62,7 +62,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Count));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -b "How to use it");
         assert_eq!(arg.get_id(), "foo");
@@ -70,7 +70,10 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::SetTrue));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), Some("How to use it"));
+        assert_eq!(
+            arg.get_help().map(|s| s.to_string()),
+            Some("How to use it".to_owned())
+        );
     }
 
     #[test]
@@ -82,7 +85,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::SetTrue));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -'b' --hello);
         assert_eq!(arg.get_id(), "foo");
@@ -91,7 +94,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::SetTrue));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -b --hello ...);
         assert_eq!(arg.get_id(), "foo");
@@ -100,7 +103,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Count));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -b --hello "How to use it");
         assert_eq!(arg.get_id(), "foo");
@@ -109,7 +112,10 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::SetTrue));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), Some("How to use it"));
+        assert_eq!(
+            arg.get_help().map(|s| s.to_string()),
+            Some("How to use it".to_owned())
+        );
     }
 
     #[test]
@@ -186,7 +192,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -'b' <NUM>);
         assert_eq!(arg.get_id(), "foo");
@@ -194,7 +200,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -b  <NUM> ...);
         assert_eq!(arg.get_id(), "foo");
@@ -202,7 +208,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Append));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: -b  <NUM> "How to use it");
         assert_eq!(arg.get_id(), "foo");
@@ -210,7 +216,10 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), Some("How to use it"));
+        assert_eq!(
+            arg.get_help().map(|s| s.to_string()),
+            Some("How to use it".to_owned())
+        );
     }
 
     #[test]
@@ -221,7 +230,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!([NUM]);
         assert_eq!(arg.get_id(), "NUM");
@@ -229,7 +238,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(!arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(<NUM>);
         assert_eq!(arg.get_id(), "NUM");
@@ -237,7 +246,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(foo: <NUM>);
         assert_eq!(arg.get_id(), "foo");
@@ -245,7 +254,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(<NUM> ...);
         assert_eq!(arg.get_id(), "NUM");
@@ -253,7 +262,7 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Append));
         assert_eq!(arg.get_num_args(), Some((1..).into()));
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), None);
+        assert_eq!(arg.get_help().map(|s| s.to_string()), None);
 
         let arg = clap::arg!(<NUM> "How to use it");
         assert_eq!(arg.get_id(), "NUM");
@@ -261,7 +270,10 @@ mod arg {
         assert!(matches!(arg.get_action(), clap::ArgAction::Set));
         assert_eq!(arg.get_num_args(), None);
         assert!(arg.is_required_set());
-        assert_eq!(arg.get_help(), Some("How to use it"));
+        assert_eq!(
+            arg.get_help().map(|s| s.to_string()),
+            Some("How to use it".to_owned())
+        );
     }
 
     #[test]

From 735d6fd1e33dcf68bae7388d60b8d1650f2f1598 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Wed, 24 Aug 2022 13:26:48 -0500
Subject: [PATCH 02/22] refactor: Extract our own display width

This added about 4 KiB to `.text` which makes sense since we duplicated
logic.
---
 Cargo.lock                  |  43 +++++++++++
 Cargo.toml                  |   4 +-
 src/builder/styled_str.rs   |  10 +++
 src/output/help.rs          |  12 +--
 src/output/mod.rs           |   2 +
 src/output/textwrap/core.rs | 144 ++++++++++++++++++++++++++++++++++++
 src/output/textwrap/mod.rs  |   1 +
 7 files changed, 209 insertions(+), 7 deletions(-)
 create mode 100644 src/output/textwrap/core.rs
 create mode 100644 src/output/textwrap/mod.rs

diff --git a/Cargo.lock b/Cargo.lock
index a4efaa5e607..582ffe35ea4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -137,7 +137,9 @@ dependencies = [
  "textwrap 0.15.0",
  "trybuild",
  "trycmd",
+ "unic-emoji-char",
  "unicase",
+ "unicode-width",
 ]
 
 [[package]]
@@ -1031,6 +1033,47 @@ dependencies = [
  "toml_edit",
 ]
 
+[[package]]
+name = "unic-char-property"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8c57a407d9b6fa02b4795eb81c5b6652060a15a7903ea981f3d723e6c0be221"
+dependencies = [
+ "unic-char-range",
+]
+
+[[package]]
+name = "unic-char-range"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0398022d5f700414f6b899e10b8348231abf9173fa93144cbc1a43b9793c1fbc"
+
+[[package]]
+name = "unic-common"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80d7ff825a6a654ee85a63e80f92f054f904f21e7d12da4e22f9834a4aaa35bc"
+
+[[package]]
+name = "unic-emoji-char"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b07221e68897210270a38bde4babb655869637af0f69407f96053a34f76494d"
+dependencies = [
+ "unic-char-property",
+ "unic-char-range",
+ "unic-ucd-version",
+]
+
+[[package]]
+name = "unic-ucd-version"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96bd2f2237fe450fcd0a1d2f5f4e91711124f7857ba2e964247776ebeeb7b0c4"
+dependencies = [
+ "unic-common",
+]
+
 [[package]]
 name = "unicase"
 version = "2.6.0"
diff --git a/Cargo.toml b/Cargo.toml
index 1c057abdaef..631a4698ce5 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -73,7 +73,7 @@ derive = ["clap_derive"]
 cargo = [] # Disable if you're not using Cargo, enables Cargo-env-var-dependent macros
 wrap_help = ["dep:terminal_size", "textwrap/terminal_size"]
 env = [] # Use environment variables during arg parsing
-unicode = ["textwrap/unicode-width", "dep:unicase"]  # Support for unicode characters in arguments and help messages
+unicode = ["textwrap/unicode-width", "dep:unicode-width", "dep:unicase"]  # Support for unicode characters in arguments and help messages
 perf = [] # Optimize for runtime performance
 
 # In-work features
@@ -95,6 +95,7 @@ atty = { version = "0.2",  optional = true }
 termcolor = { version = "1.1.1", optional = true }
 terminal_size = { version = "0.2.1", optional = true }
 backtrace = { version = "0.3", optional = true }
+unicode-width = { version = "0.1.9", optional = true }
 
 [dev-dependencies]
 trybuild = "1.0.18"
@@ -105,6 +106,7 @@ humantime = "2"
 snapbox = "0.2"
 shlex = "1.1.0"
 static_assertions = "1.1.0"
+unic-emoji-char = "0.9.0"
 
 [[example]]
 name = "demo"
diff --git a/src/builder/styled_str.rs b/src/builder/styled_str.rs
index d315e7e1bab..dd1227ff850 100644
--- a/src/builder/styled_str.rs
+++ b/src/builder/styled_str.rs
@@ -1,3 +1,5 @@
+use crate::output::display_width;
+
 /// Terminal-styling container
 #[derive(Clone, Default, Debug, PartialEq, Eq)]
 pub struct StyledStr {
@@ -37,6 +39,14 @@ impl StyledStr {
         }
     }
 
+    pub(crate) fn display_width(&self) -> usize {
+        let mut width = 0;
+        for (_, c) in &self.pieces {
+            width += display_width(c);
+        }
+        width
+    }
+
     /// HACK: Until call sites are updated to handle formatted text, extract the unformatted
     #[track_caller]
     pub(crate) fn unwrap_none(&self) -> &str {
diff --git a/src/output/help.rs b/src/output/help.rs
index 1d6e73b1c77..54b121c86d2 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -9,13 +9,11 @@ use crate::builder::PossibleValue;
 use crate::builder::Str;
 use crate::builder::StyledStr;
 use crate::builder::{render_arg_val, Arg, Command};
+use crate::output::display_width;
 use crate::output::Usage;
 use crate::util::FlatSet;
 use crate::ArgAction;
 
-// Third party
-use textwrap::core::display_width;
-
 /// `clap` Help Writer.
 ///
 /// Wraps a writer stream providing different methods to generate help for `clap` objects.
@@ -461,7 +459,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                     .expect("Only called with possible value");
                 let help_longest = possible_vals
                     .iter()
-                    .filter_map(|f| f.get_visible_help().map(|h| display_width(h.unwrap_none())))
+                    .filter_map(|f| f.get_visible_help().map(|h| h.display_width()))
                     .max()
                     .expect("Only called with possible value with help");
                 // should new line
@@ -532,7 +530,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         } else {
             // force_next_line
             let h = arg.get_help().unwrap_or_default();
-            let h_w = display_width(h.unwrap_none()) + display_width(spec_vals);
+            let h_w = h.display_width() + display_width(spec_vals);
             let taken = longest + 12;
             self.term_w >= taken
                 && (taken as f32 / self.term_w as f32) > 0.40
@@ -749,7 +747,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         } else {
             // force_next_line
             let h = cmd.get_about().unwrap_or_default();
-            let h_w = display_width(h.unwrap_none()) + display_width(spec_vals);
+            let h_w = h.display_width() + display_width(spec_vals);
             let taken = longest + 12;
             self.term_w >= taken
                 && (taken as f32 / self.term_w as f32) > 0.40
@@ -1094,6 +1092,7 @@ mod test {
     }
 
     #[test]
+    #[cfg(feature = "unicode")]
     fn display_width_handles_non_ascii() {
         // Popular Danish tongue-twister, the name of a fruit dessert.
         let text = "rødgrød med fløde";
@@ -1104,6 +1103,7 @@ mod test {
     }
 
     #[test]
+    #[cfg(feature = "unicode")]
     fn display_width_handles_emojis() {
         let text = "😂";
         // There is a single `char`...
diff --git a/src/output/mod.rs b/src/output/mod.rs
index 8a389e40012..228fc3189ff 100644
--- a/src/output/mod.rs
+++ b/src/output/mod.rs
@@ -1,7 +1,9 @@
 mod help;
+mod textwrap;
 mod usage;
 
 pub(crate) mod fmt;
 
 pub(crate) use self::help::Help;
+pub(crate) use self::textwrap::core::display_width;
 pub(crate) use self::usage::Usage;
diff --git a/src/output/textwrap/core.rs b/src/output/textwrap/core.rs
new file mode 100644
index 00000000000..c6209ed5432
--- /dev/null
+++ b/src/output/textwrap/core.rs
@@ -0,0 +1,144 @@
+/// Compute the display width of `text`
+///
+/// # Examples
+///
+/// **Note:** When the `unicode` Cargo feature is disabled, all characters are presumed to take up
+/// 1 width.  With the feature enabled, function will correctly deal with [combining characters] in
+/// their decomposed form (see [Unicode equivalence]).
+///
+/// An example of a decomposed character is “é”, which can be decomposed into: “e” followed by a
+/// combining acute accent: “◌́”.  Without the `unicode` Cargo feature, every `char` has a width of
+/// 1. This includes the combining accent:
+///
+/// ## Emojis and CJK Characters
+///
+/// Characters such as emojis and [CJK characters] used in the
+/// Chinese, Japanese, and Korean langauges are seen as double-width,
+/// even if the `unicode-width` feature is disabled:
+///
+/// # Limitations
+///
+/// The displayed width of a string cannot always be computed from the
+/// string alone. This is because the width depends on the rendering
+/// engine used. This is particularly visible with [emoji modifier
+/// sequences] where a base emoji is modified with, e.g., skin tone or
+/// hair color modifiers. It is up to the rendering engine to detect
+/// this and to produce a suitable emoji.
+///
+/// A simple example is “❤️”, which consists of “❤” (U+2764: Black
+/// Heart Symbol) followed by U+FE0F (Variation Selector-16). By
+/// itself, “❤” is a black heart, but if you follow it with the
+/// variant selector, you may get a wider red heart.
+///
+/// A more complex example would be “👨‍🦰” which should depict a man
+/// with red hair. Here the computed width is too large — and the
+/// width differs depending on the use of the `unicode-width` feature:
+///
+/// This happens because the grapheme consists of three code points:
+/// “👨” (U+1F468: Man), Zero Width Joiner (U+200D), and “🦰”
+/// (U+1F9B0: Red Hair). You can see them above in the test. With
+/// `unicode-width` enabled, the ZWJ is correctly seen as having zero
+/// width, without it is counted as a double-width character.
+///
+/// ## Terminal Support
+///
+/// Modern browsers typically do a great job at combining characters
+/// as shown above, but terminals often struggle more. As an example,
+/// Gnome Terminal version 3.38.1, shows “❤️” as a big red heart, but
+/// shows "👨‍🦰" as “👨🦰”.
+///
+/// [combining characters]: https://en.wikipedia.org/wiki/Combining_character
+/// [Unicode equivalence]: https://en.wikipedia.org/wiki/Unicode_equivalence
+/// [CJK characters]: https://en.wikipedia.org/wiki/CJK_characters
+/// [emoji modifier sequences]: https://unicode.org/emoji/charts/full-emoji-modifiers.html
+pub(crate) fn display_width(text: &str) -> usize {
+    let mut width = 0;
+    for ch in text.chars() {
+        width += ch_width(ch);
+    }
+    width
+}
+
+#[cfg(feature = "unicode")]
+fn ch_width(ch: char) -> usize {
+    unicode_width::UnicodeWidthChar::width(ch).unwrap_or(0)
+}
+
+#[cfg(not(feature = "unicode"))]
+fn ch_width(_: char) -> usize {
+    1
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[cfg(feature = "unicode")]
+    use unicode_width::UnicodeWidthChar;
+
+    #[test]
+    fn emojis_have_correct_width() {
+        use unic_emoji_char::is_emoji;
+
+        // Emojis in the Basic Latin (ASCII) and Latin-1 Supplement
+        // blocks all have a width of 1 column. This includes
+        // characters such as '#' and '©'.
+        for ch in '\u{1}'..'\u{FF}' {
+            if is_emoji(ch) {
+                let desc = format!("{:?} U+{:04X}", ch, ch as u32);
+
+                #[cfg(feature = "unicode")]
+                assert_eq!(ch.width().unwrap(), 1, "char: {}", desc);
+
+                #[cfg(not(feature = "unicode"))]
+                assert_eq!(ch_width(ch), 1, "char: {}", desc);
+            }
+        }
+
+        // Emojis in the remaining blocks of the Basic Multilingual
+        // Plane (BMP), in the Supplementary Multilingual Plane (SMP),
+        // and in the Supplementary Ideographic Plane (SIP), are all 1
+        // or 2 columns wide when unicode-width is used, and always 2
+        // columns wide otherwise. This includes all of our favorite
+        // emojis such as 😊.
+        for ch in '\u{FF}'..'\u{2FFFF}' {
+            if is_emoji(ch) {
+                let desc = format!("{:?} U+{:04X}", ch, ch as u32);
+
+                #[cfg(feature = "unicode")]
+                assert!(ch.width().unwrap() <= 2, "char: {}", desc);
+
+                #[cfg(not(feature = "unicode"))]
+                assert_eq!(ch_width(ch), 1, "char: {}", desc);
+            }
+        }
+
+        // The remaining planes contain almost no assigned code points
+        // and thus also no emojis.
+    }
+
+    #[test]
+    #[cfg(feature = "unicode")]
+    fn display_width_works() {
+        assert_eq!("Café Plain".len(), 11); // “é” is two bytes
+        assert_eq!(display_width("Café Plain"), 10);
+    }
+
+    #[test]
+    #[cfg(feature = "unicode")]
+    fn display_width_narrow_emojis() {
+        assert_eq!(display_width("⁉"), 1);
+    }
+
+    #[test]
+    #[cfg(feature = "unicode")]
+    fn display_width_narrow_emojis_variant_selector() {
+        assert_eq!(display_width("⁉\u{fe0f}"), 1);
+    }
+
+    #[test]
+    #[cfg(feature = "unicode")]
+    fn display_width_emojis() {
+        assert_eq!(display_width("😂😭🥺🤣✨😍🙏🥰😊🔥"), 20);
+    }
+}
diff --git a/src/output/textwrap/mod.rs b/src/output/textwrap/mod.rs
new file mode 100644
index 00000000000..90d7cc3655d
--- /dev/null
+++ b/src/output/textwrap/mod.rs
@@ -0,0 +1 @@
+pub(crate) mod core;

From 37f2efb0bdd3c9bef34c29072182601e8f97e81d Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Wed, 24 Aug 2022 15:53:23 -0500
Subject: [PATCH 03/22] perf: Vendor textwrap parts we need

The immediate benefit is binary size but this also makes us more
flexible on the implementation, like allowing wrapping of `StyledStr`.

This removed 12 KiB from `.text`

This helps towards #1365 and probably #2037
---
 Cargo.lock                             |  25 +-----
 Cargo.toml                             |   5 +-
 src/output/help.rs                     |  33 +++-----
 src/output/mod.rs                      |   1 +
 src/output/textwrap/mod.rs             | 112 +++++++++++++++++++++++++
 src/output/textwrap/word_separators.rs |  91 ++++++++++++++++++++
 src/output/textwrap/wrap_algorithms.rs |  44 ++++++++++
 7 files changed, 264 insertions(+), 47 deletions(-)
 create mode 100644 src/output/textwrap/word_separators.rs
 create mode 100644 src/output/textwrap/wrap_algorithms.rs

diff --git a/Cargo.lock b/Cargo.lock
index 582ffe35ea4..3177895255e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -113,7 +113,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a0610544180c38b88101fecf2dd634b174a62eef6946f84dfc6a7127512b381c"
 dependencies = [
  "bitflags",
- "textwrap 0.11.0",
+ "textwrap",
  "unicode-width",
 ]
 
@@ -133,8 +133,7 @@ dependencies = [
  "static_assertions",
  "strsim",
  "termcolor",
- "terminal_size 0.2.1",
- "textwrap 0.15.0",
+ "terminal_size",
  "trybuild",
  "trycmd",
  "unic-emoji-char",
@@ -931,16 +930,6 @@ dependencies = [
  "winapi-util",
 ]
 
-[[package]]
-name = "terminal_size"
-version = "0.1.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "633c1a546cee861a1a6d0dc69ebeca693bf4296661ba7852b9d21d159e0506df"
-dependencies = [
- "libc",
- "winapi",
-]
-
 [[package]]
 name = "terminal_size"
 version = "0.2.1"
@@ -960,16 +949,6 @@ dependencies = [
  "unicode-width",
 ]
 
-[[package]]
-name = "textwrap"
-version = "0.15.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b1141d4d61095b28419e22cb0bbf02755f5e54e0526f97f1e3d1d160e60885fb"
-dependencies = [
- "terminal_size 0.1.17",
- "unicode-width",
-]
-
 [[package]]
 name = "tinytemplate"
 version = "1.2.1"
diff --git a/Cargo.toml b/Cargo.toml
index 631a4698ce5..37e184e8fd4 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -71,9 +71,9 @@ suggestions = ["dep:strsim"]
 deprecated = ["clap_derive?/deprecated"] # Guided experience to prepare for next breaking release (at different stages of development, this may become default)
 derive = ["clap_derive"]
 cargo = [] # Disable if you're not using Cargo, enables Cargo-env-var-dependent macros
-wrap_help = ["dep:terminal_size", "textwrap/terminal_size"]
+wrap_help = ["dep:terminal_size"]
 env = [] # Use environment variables during arg parsing
-unicode = ["textwrap/unicode-width", "dep:unicode-width", "dep:unicase"]  # Support for unicode characters in arguments and help messages
+unicode = ["dep:unicode-width", "dep:unicase"]  # Support for unicode characters in arguments and help messages
 perf = [] # Optimize for runtime performance
 
 # In-work features
@@ -88,7 +88,6 @@ bench = false
 clap_derive = { path = "./clap_derive", version = "=4.0.0-alpha.0", optional = true }
 clap_lex = { path = "./clap_lex", version = "0.2.2" }
 bitflags = "1.2"
-textwrap = { version = "0.15.0", default-features = false, features = [] }
 unicase = { version = "2.6", optional = true }
 strsim = { version = "0.10",  optional = true }
 atty = { version = "0.2",  optional = true }
diff --git a/src/output/help.rs b/src/output/help.rs
index 54b121c86d2..c17d184f1a4 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -10,6 +10,7 @@ use crate::builder::Str;
 use crate::builder::StyledStr;
 use crate::builder::{render_arg_val, Arg, Command};
 use crate::output::display_width;
+use crate::output::wrap;
 use crate::output::Usage;
 use crate::util::FlatSet;
 use crate::ArgAction;
@@ -355,7 +356,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             self.cmd.get_before_help()
         };
         if let Some(output) = before_help {
-            self.none(text_wrapper(
+            self.none(wrap(
                 &output.unwrap_none().replace("{n}", "\n"),
                 self.term_w,
             ));
@@ -374,7 +375,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         };
         if let Some(output) = after_help {
             self.none("\n\n");
-            self.none(text_wrapper(
+            self.none(wrap(
                 &output.unwrap_none().replace("{n}", "\n"),
                 self.term_w,
             ));
@@ -415,7 +416,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             // Determine how many newlines we need to insert
             let avail_chars = self.term_w - spaces;
             debug!("Help::help: Usable space...{}", avail_chars);
-            help = text_wrapper(&help.replace("{n}", "\n"), avail_chars);
+            help = wrap(&help.replace("{n}", "\n"), avail_chars);
         } else {
             debug!("No");
         }
@@ -498,7 +499,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                             usize::MAX
                         };
 
-                        let help = text_wrapper(help.unwrap_none(), avail_chars);
+                        let help = wrap(help.unwrap_none(), avail_chars);
                         let mut help = help.lines();
 
                         self.none(help.next().unwrap_or_default());
@@ -657,7 +658,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             if before_new_line {
                 self.none("\n");
             }
-            self.none(text_wrapper(output.unwrap_none(), self.term_w));
+            self.none(wrap(output.unwrap_none(), self.term_w));
             if after_new_line {
                 self.none("\n");
             }
@@ -669,7 +670,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             if before_new_line {
                 self.none("\n");
             }
-            self.none(text_wrapper(author, self.term_w));
+            self.none(wrap(author, self.term_w));
             if after_new_line {
                 self.none("\n");
             }
@@ -682,7 +683,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             .get_version()
             .or_else(|| self.cmd.get_long_version());
         if let Some(output) = version {
-            self.none(text_wrapper(output, self.term_w));
+            self.none(wrap(output, self.term_w));
         }
     }
 }
@@ -906,7 +907,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     fn write_display_name(&mut self) {
         debug!("Help::write_display_name");
 
-        let display_name = text_wrapper(
+        let display_name = wrap(
             &self
                 .cmd
                 .get_display_name()
@@ -926,10 +927,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                 // In case we're dealing with subcommands i.e. git mv is translated to git-mv
                 bn.replace(' ', "-")
             } else {
-                text_wrapper(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
+                wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
             }
         } else {
-            text_wrapper(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
+            wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
         };
         self.good(&bin_name);
     }
@@ -1071,16 +1072,6 @@ fn should_show_subcommand(subcommand: &Command) -> bool {
     !subcommand.is_hide_set()
 }
 
-fn text_wrapper(help: &str, width: usize) -> String {
-    let wrapper = textwrap::Options::new(width)
-        .break_words(false)
-        .word_splitter(textwrap::WordSplitter::NoHyphenation);
-    help.lines()
-        .map(|line| textwrap::fill(line, &wrapper))
-        .collect::<Vec<String>>()
-        .join("\n")
-}
-
 #[cfg(test)]
 mod test {
     use super::*;
@@ -1088,7 +1079,7 @@ mod test {
     #[test]
     fn wrap_help_last_word() {
         let help = String::from("foo bar baz");
-        assert_eq!(text_wrapper(&help, 5), "foo\nbar\nbaz");
+        assert_eq!(wrap(&help, 5), "foo\nbar\nbaz");
     }
 
     #[test]
diff --git a/src/output/mod.rs b/src/output/mod.rs
index 228fc3189ff..1d7a4316a75 100644
--- a/src/output/mod.rs
+++ b/src/output/mod.rs
@@ -6,4 +6,5 @@ pub(crate) mod fmt;
 
 pub(crate) use self::help::Help;
 pub(crate) use self::textwrap::core::display_width;
+pub(crate) use self::textwrap::wrap;
 pub(crate) use self::usage::Usage;
diff --git a/src/output/textwrap/mod.rs b/src/output/textwrap/mod.rs
index 90d7cc3655d..c6e831f65cf 100644
--- a/src/output/textwrap/mod.rs
+++ b/src/output/textwrap/mod.rs
@@ -1 +1,113 @@
+//! Fork of `textwrap` crate
+//!
+//! Benefits of forking:
+//! - Pull in only what we need rather than relying on the compiler to remove what we don't need
+//! - `LineWrapper` is able to incrementally wrap which will help with `StyledStr
+
 pub(crate) mod core;
+pub(crate) mod word_separators;
+pub(crate) mod wrap_algorithms;
+
+pub(crate) fn wrap(content: &str, hard_width: usize) -> String {
+    let mut wrapper = wrap_algorithms::LineWrapper::new(hard_width);
+    let mut total = Vec::new();
+    for line in content.split_inclusive('\n') {
+        wrapper.reset();
+        let line = word_separators::find_words_ascii_space(line).collect::<Vec<_>>();
+        total.extend(wrapper.wrap(line));
+    }
+    total.join("")
+}
+
+#[cfg(test)]
+mod test {
+    /// Compatibility shim to keep textwrap's tests
+    fn wrap(content: &str, hard_width: usize) -> Vec<String> {
+        super::wrap(content, hard_width)
+            .trim_end()
+            .split('\n')
+            .map(|s| s.to_owned())
+            .collect::<Vec<_>>()
+    }
+
+    #[test]
+    fn no_wrap() {
+        assert_eq!(wrap("foo", 10), vec!["foo"]);
+    }
+
+    #[test]
+    fn wrap_simple() {
+        assert_eq!(wrap("foo bar baz", 5), vec!["foo", "bar", "baz"]);
+    }
+
+    #[test]
+    fn to_be_or_not() {
+        assert_eq!(
+            wrap("To be, or not to be, that is the question.", 10),
+            vec!["To be, or", "not to be,", "that is", "the", "question."]
+        );
+    }
+
+    #[test]
+    fn multiple_words_on_first_line() {
+        assert_eq!(wrap("foo bar baz", 10), vec!["foo bar", "baz"]);
+    }
+
+    #[test]
+    fn long_word() {
+        assert_eq!(wrap("foo", 0), vec!["foo"]);
+    }
+
+    #[test]
+    fn long_words() {
+        assert_eq!(wrap("foo bar", 0), vec!["foo", "bar"]);
+    }
+
+    #[test]
+    fn max_width() {
+        assert_eq!(wrap("foo bar", usize::MAX), vec!["foo bar"]);
+
+        let text = "Hello there! This is some English text. \
+                    It should not be wrapped given the extents below.";
+        assert_eq!(wrap(text, usize::MAX), vec![text]);
+    }
+
+    #[test]
+    fn leading_whitespace() {
+        assert_eq!(wrap("  foo bar", 6), vec!["  foo", "bar"]);
+    }
+
+    #[test]
+    fn leading_whitespace_empty_first_line() {
+        // If there is no space for the first word, the first line
+        // will be empty. This is because the string is split into
+        // words like [" ", "foobar ", "baz"], which puts "foobar " on
+        // the second line. We never output trailing whitespace
+        assert_eq!(wrap(" foobar baz", 6), vec!["", "foobar", "baz"]);
+    }
+
+    #[test]
+    fn trailing_whitespace() {
+        // Whitespace is only significant inside a line. After a line
+        // gets too long and is broken, the first word starts in
+        // column zero and is not indented.
+        assert_eq!(wrap("foo     bar     baz  ", 5), vec!["foo", "bar", "baz"]);
+    }
+
+    #[test]
+    fn issue_99() {
+        // We did not reset the in_whitespace flag correctly and did
+        // not handle single-character words after a line break.
+        assert_eq!(
+            wrap("aaabbbccc x yyyzzzwww", 9),
+            vec!["aaabbbccc", "x", "yyyzzzwww"]
+        );
+    }
+
+    #[test]
+    fn issue_129() {
+        // The dash is an em-dash which takes up four bytes. We used
+        // to panic since we tried to index into the character.
+        assert_eq!(wrap("x – x", 1), vec!["x", "–", "x"]);
+    }
+}
diff --git a/src/output/textwrap/word_separators.rs b/src/output/textwrap/word_separators.rs
new file mode 100644
index 00000000000..ac09231d56e
--- /dev/null
+++ b/src/output/textwrap/word_separators.rs
@@ -0,0 +1,91 @@
+pub(crate) fn find_words_ascii_space(line: &str) -> impl Iterator<Item = &'_ str> + '_ {
+    let mut start = 0;
+    let mut in_whitespace = false;
+    let mut char_indices = line.char_indices();
+
+    std::iter::from_fn(move || {
+        for (idx, ch) in char_indices.by_ref() {
+            if in_whitespace && ch != ' ' {
+                let word = &line[start..idx];
+                start = idx;
+                in_whitespace = ch == ' ';
+                return Some(word);
+            }
+
+            in_whitespace = ch == ' ';
+        }
+
+        if start < line.len() {
+            let word = &line[start..];
+            start = line.len();
+            return Some(word);
+        }
+
+        None
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    macro_rules! test_find_words {
+        ($ascii_name:ident,
+         $([ $line:expr, $ascii_words:expr ]),+) => {
+            #[test]
+            fn $ascii_name() {
+                $(
+                    let expected_words: Vec<&str> = $ascii_words.to_vec();
+                    let actual_words = find_words_ascii_space($line)
+                        .collect::<Vec<_>>();
+                    assert_eq!(actual_words, expected_words, "Line: {:?}", $line);
+                )+
+            }
+        };
+    }
+
+    test_find_words!(ascii_space_empty, ["", []]);
+
+    test_find_words!(ascii_single_word, ["foo", ["foo"]]);
+
+    test_find_words!(ascii_two_words, ["foo bar", ["foo ", "bar"]]);
+
+    test_find_words!(
+        ascii_multiple_words,
+        ["foo bar", ["foo ", "bar"]],
+        ["x y z", ["x ", "y ", "z"]]
+    );
+
+    test_find_words!(ascii_only_whitespace, [" ", [" "]], ["    ", ["    "]]);
+
+    test_find_words!(
+        ascii_inter_word_whitespace,
+        ["foo   bar", ["foo   ", "bar"]]
+    );
+
+    test_find_words!(ascii_trailing_whitespace, ["foo   ", ["foo   "]]);
+
+    test_find_words!(ascii_leading_whitespace, ["   foo", ["   ", "foo"]]);
+
+    test_find_words!(
+        ascii_multi_column_char,
+        ["\u{1f920}", ["\u{1f920}"]] // cowboy emoji 🤠
+    );
+
+    test_find_words!(
+        ascii_hyphens,
+        ["foo-bar", ["foo-bar"]],
+        ["foo- bar", ["foo- ", "bar"]],
+        ["foo - bar", ["foo ", "- ", "bar"]],
+        ["foo -bar", ["foo ", "-bar"]]
+    );
+
+    test_find_words!(ascii_newline, ["foo\nbar", ["foo\nbar"]]);
+
+    test_find_words!(ascii_tab, ["foo\tbar", ["foo\tbar"]]);
+
+    test_find_words!(
+        ascii_non_breaking_space,
+        ["foo\u{00A0}bar", ["foo\u{00A0}bar"]]
+    );
+}
diff --git a/src/output/textwrap/wrap_algorithms.rs b/src/output/textwrap/wrap_algorithms.rs
new file mode 100644
index 00000000000..019cc04ffec
--- /dev/null
+++ b/src/output/textwrap/wrap_algorithms.rs
@@ -0,0 +1,44 @@
+use super::core::display_width;
+
+#[derive(Debug)]
+pub(crate) struct LineWrapper {
+    line_width: usize,
+    hard_width: usize,
+}
+
+impl LineWrapper {
+    pub(crate) fn new(hard_width: usize) -> Self {
+        Self {
+            line_width: 0,
+            hard_width,
+        }
+    }
+
+    pub(crate) fn reset(&mut self) {
+        self.line_width = 0;
+    }
+
+    pub(crate) fn wrap<'w>(&mut self, mut words: Vec<&'w str>) -> Vec<&'w str> {
+        let mut i = 0;
+        while i < words.len() {
+            let word = &words[i];
+            let trimmed = word.trim_end();
+            let word_width = display_width(trimmed);
+            let trimmed_delta = word.len() - trimmed.len();
+            if i != 0 && self.hard_width < self.line_width + word_width {
+                if 0 < i {
+                    let last = i - 1;
+                    let trimmed = words[last].trim_end();
+                    words[last] = trimmed;
+                }
+                words.insert(i, "\n");
+                i += 1;
+                self.reset();
+            }
+            self.line_width += word_width + trimmed_delta;
+
+            i += 1;
+        }
+        words
+    }
+}

From 1bd9365bdf2e2a765d7150386d02912503b9e965 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Wed, 24 Aug 2022 18:20:16 -0500
Subject: [PATCH 04/22] perf(help): Reduce binary size

This dropped us about 1.8 KiB
---
 src/builder/styled_str.rs   | 1 +
 src/output/textwrap/core.rs | 1 +
 2 files changed, 2 insertions(+)

diff --git a/src/builder/styled_str.rs b/src/builder/styled_str.rs
index dd1227ff850..eb5036173e1 100644
--- a/src/builder/styled_str.rs
+++ b/src/builder/styled_str.rs
@@ -39,6 +39,7 @@ impl StyledStr {
         }
     }
 
+    #[inline(never)]
     pub(crate) fn display_width(&self) -> usize {
         let mut width = 0;
         for (_, c) in &self.pieces {
diff --git a/src/output/textwrap/core.rs b/src/output/textwrap/core.rs
index c6209ed5432..dac98d55289 100644
--- a/src/output/textwrap/core.rs
+++ b/src/output/textwrap/core.rs
@@ -51,6 +51,7 @@
 /// [Unicode equivalence]: https://en.wikipedia.org/wiki/Unicode_equivalence
 /// [CJK characters]: https://en.wikipedia.org/wiki/CJK_characters
 /// [emoji modifier sequences]: https://unicode.org/emoji/charts/full-emoji-modifiers.html
+#[inline(never)]
 pub(crate) fn display_width(text: &str) -> usize {
     let mut width = 0;
     for ch in text.chars() {

From c2e80beed295df17bdbc1b7772fa562796acdd6a Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 09:04:04 -0500
Subject: [PATCH 05/22] fix(help): Allow stylized help template

---
 src/builder/styled_str.rs | 16 ++++++++++------
 src/output/help.rs        |  8 +++++++-
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/src/builder/styled_str.rs b/src/builder/styled_str.rs
index eb5036173e1..8a5fb149bb6 100644
--- a/src/builder/styled_str.rs
+++ b/src/builder/styled_str.rs
@@ -13,27 +13,31 @@ impl StyledStr {
     }
 
     pub(crate) fn good(&mut self, msg: impl Into<String>) {
-        self.stylize(Some(Style::Good), msg.into());
+        self.stylize_(Some(Style::Good), msg.into());
     }
 
     pub(crate) fn warning(&mut self, msg: impl Into<String>) {
-        self.stylize(Some(Style::Warning), msg.into());
+        self.stylize_(Some(Style::Warning), msg.into());
     }
 
     pub(crate) fn error(&mut self, msg: impl Into<String>) {
-        self.stylize(Some(Style::Error), msg.into());
+        self.stylize_(Some(Style::Error), msg.into());
     }
 
     #[allow(dead_code)]
     pub(crate) fn hint(&mut self, msg: impl Into<String>) {
-        self.stylize(Some(Style::Hint), msg.into());
+        self.stylize_(Some(Style::Hint), msg.into());
     }
 
     pub(crate) fn none(&mut self, msg: impl Into<String>) {
-        self.stylize(None, msg.into());
+        self.stylize_(None, msg.into());
     }
 
-    fn stylize(&mut self, style: Option<Style>, msg: String) {
+    pub(crate) fn stylize(&mut self, style: impl Into<Option<Style>>, msg: impl Into<String>) {
+        self.stylize_(style.into(), msg.into());
+    }
+
+    fn stylize_(&mut self, style: Option<Style>, msg: String) {
         if !msg.is_empty() {
             self.pieces.push((style, msg));
         }
diff --git a/src/output/help.rs b/src/output/help.rs
index c17d184f1a4..a49a539660d 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -81,7 +81,13 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         if let Some(h) = self.cmd.get_override_help() {
             self.extend(h);
         } else if let Some(tmpl) = self.cmd.get_help_template() {
-            self.write_templated_help(tmpl.unwrap_none());
+            for (style, content) in tmpl.iter() {
+                if style == None {
+                    self.write_templated_help(content);
+                } else {
+                    self.writer.stylize(style, content);
+                }
+            }
         } else {
             let pos = self
                 .cmd

From 5e1d2d349b140f38cf4eedf98a90dcd147f6aa26 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 09:07:39 -0500
Subject: [PATCH 06/22] fix(debug): Reduce noise

---
 src/output/help.rs | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index a49a539660d..7eaf7db2822 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -398,33 +398,30 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         longest: usize,
     ) {
         debug!("Help::help");
-        let mut help = String::from(about.unwrap_none()) + spec_vals;
-        debug!("Help::help: Next Line...{:?}", next_line_help);
+
+        // Is help on next line, if so then indent
+        if next_line_help {
+            debug!("Help::help: Next Line...{:?}", next_line_help);
+            self.none(format!("\n{}{}{}", TAB, TAB, TAB));
+        }
 
         let spaces = if next_line_help {
             12 // "tab" * 3
         } else {
             longest + 12
         };
-
+        let mut help = String::from(about.unwrap_none()) + spec_vals;
         let too_long = spaces + display_width(&help) >= self.term_w;
-
-        // Is help on next line, if so then indent
-        if next_line_help {
-            self.none(format!("\n{}{}{}", TAB, TAB, TAB));
-        }
-
-        debug!("Help::help: Too long...");
         if too_long && spaces <= self.term_w || help.contains("{n}") {
-            debug!("Yes");
-            debug!("Help::help: help...{}", help);
-            debug!("Help::help: help width...{}", display_width(&help));
             // Determine how many newlines we need to insert
             let avail_chars = self.term_w - spaces;
-            debug!("Help::help: Usable space...{}", avail_chars);
+            debug!(
+                "Help::help: too_long, help_width={}, spaces={}, avail={}",
+                spaces,
+                display_width(&help),
+                avail_chars
+            );
             help = wrap(&help.replace("{n}", "\n"), avail_chars);
-        } else {
-            debug!("No");
         }
         if let Some(part) = help.lines().next() {
             self.none(part);

From c228c8830971aefe6cb2682d187f2bc901300025 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 09:12:11 -0500
Subject: [PATCH 07/22] perf(help): Prefer small binary to speed

---
 src/output/help.rs | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index 7eaf7db2822..3cd225fea0d 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -411,18 +411,14 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             longest + 12
         };
         let mut help = String::from(about.unwrap_none()) + spec_vals;
-        let too_long = spaces + display_width(&help) >= self.term_w;
-        if too_long && spaces <= self.term_w || help.contains("{n}") {
-            // Determine how many newlines we need to insert
-            let avail_chars = self.term_w - spaces;
-            debug!(
-                "Help::help: too_long, help_width={}, spaces={}, avail={}",
-                spaces,
-                display_width(&help),
-                avail_chars
-            );
-            help = wrap(&help.replace("{n}", "\n"), avail_chars);
-        }
+        let avail_chars = self.term_w.saturating_sub(spaces);
+        debug!(
+            "Help::help: help_width={}, spaces={}, avail={}",
+            spaces,
+            display_width(&help),
+            avail_chars
+        );
+        help = wrap(&help.replace("{n}", "\n"), avail_chars);
         if let Some(part) = help.lines().next() {
             self.none(part);
         }

From 764ec6903ba7dff2f57f1779f7beeff7a17dfcc1 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 09:42:32 -0500
Subject: [PATCH 08/22] feat: Allow stylized arg helps

This adds about 5 KiB to `.text`
---
 src/builder/styled_str.rs | 43 +++++++++++++++++++++++++++++++
 src/output/help.rs        | 54 +++++++++++++++++----------------------
 src/output/mod.rs         |  2 +-
 3 files changed, 67 insertions(+), 32 deletions(-)

diff --git a/src/builder/styled_str.rs b/src/builder/styled_str.rs
index 8a5fb149bb6..b16cd71a6b6 100644
--- a/src/builder/styled_str.rs
+++ b/src/builder/styled_str.rs
@@ -1,4 +1,5 @@
 use crate::output::display_width;
+use crate::output::textwrap;
 
 /// Terminal-styling container
 #[derive(Clone, Default, Debug, PartialEq, Eq)]
@@ -37,6 +38,44 @@ impl StyledStr {
         self.stylize_(style.into(), msg.into());
     }
 
+    pub(crate) fn replace_newline(&mut self) {
+        for (_, content) in &mut self.pieces {
+            *content = content.replace("{n}", "\n");
+        }
+    }
+
+    pub(crate) fn indent(&mut self, initial: &str, trailing: &str) {
+        if let Some((_, first)) = self.pieces.first_mut() {
+            first.insert_str(0, initial);
+        }
+        let mut line_sep = "\n".to_owned();
+        line_sep.push_str(trailing);
+        for (_, content) in &mut self.pieces {
+            *content = content.replace('\n', &line_sep);
+        }
+    }
+
+    pub(crate) fn wrap(&mut self, hard_width: usize) {
+        let mut wrapper = textwrap::wrap_algorithms::LineWrapper::new(hard_width);
+        for (_, content) in &mut self.pieces {
+            let mut total = Vec::new();
+            for (i, line) in content.split_inclusive('\n').enumerate() {
+                if 0 < i {
+                    // start of a section does not imply newline
+                    wrapper.reset();
+                }
+                let line =
+                    textwrap::word_separators::find_words_ascii_space(line).collect::<Vec<_>>();
+                total.extend(wrapper.wrap(line));
+            }
+            let total = total.join("");
+            *content = total;
+        }
+        if let Some((_, last)) = self.pieces.last_mut() {
+            *last = last.trim_end().to_owned();
+        }
+    }
+
     fn stylize_(&mut self, style: Option<Style>, msg: String) {
         if !msg.is_empty() {
             self.pieces.push((style, msg));
@@ -75,6 +114,10 @@ impl StyledStr {
         self.pieces.iter().map(|(s, c)| (*s, c.as_str()))
     }
 
+    pub(crate) fn into_iter(self) -> impl Iterator<Item = (Option<Style>, String)> {
+        self.pieces.into_iter()
+    }
+
     pub(crate) fn extend(
         &mut self,
         other: impl IntoIterator<Item = (impl Into<Option<Style>>, impl Into<String>)>,
diff --git a/src/output/help.rs b/src/output/help.rs
index 3cd225fea0d..d02d0b837cd 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -128,16 +128,12 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         self.writer.none(msg);
     }
 
-    #[inline(never)]
+    fn get_spaces(&self, n: usize) -> String {
+        " ".repeat(n)
+    }
+
     fn spaces(&mut self, n: usize) {
-        // A string with 64 consecutive spaces.
-        const SHORT_SPACE: &str =
-            "                                                                ";
-        if let Some(short) = SHORT_SPACE.get(..n) {
-            self.none(short);
-        } else {
-            self.none(" ".repeat(n));
-        }
+        self.none(self.get_spaces(n));
     }
 
     /// Writes help for each argument in the order they were declared to the wrapped stream.
@@ -405,38 +401,34 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             self.none(format!("\n{}{}{}", TAB, TAB, TAB));
         }
 
+        let trailing_indent = if next_line_help {
+            TAB_WIDTH * 3
+        } else if let Some(true) = arg.map(|a| a.is_positional()) {
+            longest + TAB_WIDTH * 2
+        } else {
+            longest + TAB_WIDTH * 3
+        };
+        let trailing_indent = self.get_spaces(trailing_indent);
+
         let spaces = if next_line_help {
             12 // "tab" * 3
         } else {
             longest + 12
         };
-        let mut help = String::from(about.unwrap_none()) + spec_vals;
+        let mut help = about.clone();
+        help.replace_newline();
+        help.none(spec_vals);
         let avail_chars = self.term_w.saturating_sub(spaces);
         debug!(
             "Help::help: help_width={}, spaces={}, avail={}",
             spaces,
-            display_width(&help),
+            help.display_width(),
             avail_chars
         );
-        help = wrap(&help.replace("{n}", "\n"), avail_chars);
-        if let Some(part) = help.lines().next() {
-            self.none(part);
-        }
-
-        // indent of help
-        let spaces = if next_line_help {
-            TAB_WIDTH * 3
-        } else if let Some(true) = arg.map(|a| a.is_positional()) {
-            longest + TAB_WIDTH * 2
-        } else {
-            longest + TAB_WIDTH * 3
-        };
-
-        for part in help.lines().skip(1) {
-            self.none("\n");
-            self.spaces(spaces);
-            self.none(part);
-        }
+        help.wrap(avail_chars);
+        help.indent("", &trailing_indent);
+        let help_is_empty = help.is_empty();
+        self.writer.extend(help.into_iter());
 
         if let Some(arg) = arg {
             const DASH_SPACE: usize = "- ".len();
@@ -447,7 +439,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                 && possible_vals.iter().any(PossibleValue::should_show_help)
             {
                 debug!("Help::help: Found possible vals...{:?}", possible_vals);
-                if !help.is_empty() {
+                if !help_is_empty {
                     self.none("\n\n");
                     self.spaces(spaces);
                 }
diff --git a/src/output/mod.rs b/src/output/mod.rs
index 1d7a4316a75..9eb5fa1f5b8 100644
--- a/src/output/mod.rs
+++ b/src/output/mod.rs
@@ -1,8 +1,8 @@
 mod help;
-mod textwrap;
 mod usage;
 
 pub(crate) mod fmt;
+pub(crate) mod textwrap;
 
 pub(crate) use self::help::Help;
 pub(crate) use self::textwrap::core::display_width;

From 2d5b3263c5e1446a2855002fd05aee85f29c154f Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 10:39:39 -0500
Subject: [PATCH 09/22] feat: Allow styling of rest of StyledStr help

---
 src/builder/styled_str.rs | 15 -------------
 src/output/help.rs        | 44 +++++++++++++++++++--------------------
 2 files changed, 22 insertions(+), 37 deletions(-)

diff --git a/src/builder/styled_str.rs b/src/builder/styled_str.rs
index b16cd71a6b6..390c26cbc39 100644
--- a/src/builder/styled_str.rs
+++ b/src/builder/styled_str.rs
@@ -91,21 +91,6 @@ impl StyledStr {
         width
     }
 
-    /// HACK: Until call sites are updated to handle formatted text, extract the unformatted
-    #[track_caller]
-    pub(crate) fn unwrap_none(&self) -> &str {
-        match self.pieces.len() {
-            0 => "",
-            1 => {
-                if self.pieces[0].0 != None {
-                    panic!("{}", crate::INTERNAL_ERROR_MSG)
-                }
-                self.pieces[0].1.as_str()
-            }
-            _ => panic!("{}", crate::INTERNAL_ERROR_MSG),
-        }
-    }
-
     pub(crate) fn is_empty(&self) -> bool {
         self.pieces.is_empty()
     }
diff --git a/src/output/help.rs b/src/output/help.rs
index d02d0b837cd..fbba2c8b66a 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -358,10 +358,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             self.cmd.get_before_help()
         };
         if let Some(output) = before_help {
-            self.none(wrap(
-                &output.unwrap_none().replace("{n}", "\n"),
-                self.term_w,
-            ));
+            let mut output = output.clone();
+            output.replace_newline();
+            output.wrap(self.term_w);
+            self.writer.extend(output.into_iter());
             self.none("\n\n");
         }
     }
@@ -377,10 +377,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         };
         if let Some(output) = after_help {
             self.none("\n\n");
-            self.none(wrap(
-                &output.unwrap_none().replace("{n}", "\n"),
-                self.term_w,
-            ));
+            let mut output = output.clone();
+            output.replace_newline();
+            output.wrap(self.term_w);
+            self.writer.extend(output.into_iter());
         }
     }
 
@@ -461,11 +461,12 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                     self.term_w >= taken && self.term_w < taken + COLON_SPACE + help_longest;
 
                 let spaces = spaces + TAB_WIDTH - DASH_SPACE;
-                let spaces_help = if possible_value_new_line {
+                let trailing_indent = if possible_value_new_line {
                     spaces + DASH_SPACE
                 } else {
                     spaces + longest + DASH_SPACE + COLON_SPACE
                 };
+                let trailing_indent = self.get_spaces(trailing_indent);
 
                 for pv in possible_vals.iter().filter(|pv| !pv.is_hide_set()) {
                     self.none("\n");
@@ -477,28 +478,24 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
 
                         if possible_value_new_line {
                             self.none(":\n");
-                            self.spaces(spaces_help);
+                            self.spaces(trailing_indent.len());
                         } else {
                             self.none(": ");
                             // To align help messages
                             self.spaces(longest - display_width(pv.get_name()));
                         }
 
-                        let avail_chars = if self.term_w > spaces_help {
-                            self.term_w - spaces_help
+                        let avail_chars = if self.term_w > trailing_indent.len() {
+                            self.term_w - trailing_indent.len()
                         } else {
                             usize::MAX
                         };
 
-                        let help = wrap(help.unwrap_none(), avail_chars);
-                        let mut help = help.lines();
-
-                        self.none(help.next().unwrap_or_default());
-                        for part in help {
-                            self.none("\n");
-                            self.spaces(spaces_help);
-                            self.none(part);
-                        }
+                        let mut help = help.clone();
+                        help.replace_newline();
+                        help.wrap(avail_chars);
+                        help.indent("", &trailing_indent);
+                        self.writer.extend(help.into_iter());
                     }
                 }
             }
@@ -649,7 +646,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             if before_new_line {
                 self.none("\n");
             }
-            self.none(wrap(output.unwrap_none(), self.term_w));
+            let mut output = output.clone();
+            output.replace_newline();
+            output.wrap(self.term_w);
+            self.writer.extend(output.into_iter());
             if after_new_line {
                 self.none("\n");
             }

From 0a15d9ad0c6b7b78c94059e79fb9287132a9f6db Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 11:01:03 -0500
Subject: [PATCH 10/22] refactor(help): Clarify intent

---
 src/output/help.rs | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index fbba2c8b66a..e66e9a7f7f1 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -99,11 +99,12 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                 .any(|arg| should_show_arg(self.use_long, arg));
             let subcmds = self.cmd.has_visible_subcommands();
 
-            if non_pos || pos || subcmds {
-                self.write_templated_help(Self::DEFAULT_TEMPLATE);
+            let template = if non_pos || pos || subcmds {
+                Self::DEFAULT_TEMPLATE
             } else {
-                self.write_templated_help(Self::DEFAULT_NO_ARGS_TEMPLATE);
-            }
+                Self::DEFAULT_NO_ARGS_TEMPLATE
+            };
+            self.write_templated_help(template);
         }
 
         self.none("\n");

From 2dd493a295a9be3fc36f03e9e9a20546d47867eb Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 11:29:23 -0500
Subject: [PATCH 11/22] perf(help): Reduce code size for arg generation

---
 src/output/help.rs | 97 +++++++++++++++++++---------------------------
 1 file changed, 39 insertions(+), 58 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index e66e9a7f7f1..5d4b73bb5b1 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -137,38 +137,8 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         self.none(self.get_spaces(n));
     }
 
-    /// Writes help for each argument in the order they were declared to the wrapped stream.
-    fn write_args_unsorted(&mut self, args: &[&Arg]) {
-        debug!("Help::write_args_unsorted");
-        // The shortest an arg can legally be is 2 (i.e. '-x')
-        let mut longest = 2;
-        let mut arg_v = Vec::with_capacity(10);
-
-        for &arg in args
-            .iter()
-            .filter(|arg| should_show_arg(self.use_long, *arg))
-        {
-            if arg.longest_filter() {
-                longest = longest.max(display_width(&arg.to_string()));
-                debug!(
-                    "Help::write_args_unsorted: arg={:?} longest={}",
-                    arg.get_id(),
-                    longest
-                );
-            }
-            arg_v.push(arg)
-        }
-
-        let next_line_help = self.will_args_wrap(args, longest);
-
-        let argc = arg_v.len();
-        for (i, arg) in arg_v.iter().enumerate() {
-            self.write_arg(arg, i + 1 == argc, next_line_help, longest);
-        }
-    }
-
     /// Sorts arguments by length and display order and write their help to the wrapped stream.
-    fn write_args(&mut self, args: &[&Arg], _category: &str) {
+    fn write_args(&mut self, args: &[&Arg], _category: &str, sort_key: ArgSortKey) {
         debug!("Help::write_args {}", _category);
         // The shortest an arg can legally be is 2 (i.e. '-x')
         let mut longest = 2;
@@ -190,32 +160,14 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                 );
             }
 
-            // Formatting key like this to ensure that:
-            // 1. Argument has long flags are printed just after short flags.
-            // 2. For two args both have short flags like `-c` and `-C`, the
-            //    `-C` arg is printed just after the `-c` arg
-            // 3. For args without short or long flag, print them at last(sorted
-            //    by arg name).
-            // Example order: -a, -b, -B, -s, --select-file, --select-folder, -x
-
-            let key = if let Some(x) = arg.get_short() {
-                let mut s = x.to_ascii_lowercase().to_string();
-                s.push(if x.is_ascii_lowercase() { '0' } else { '1' });
-                s
-            } else if let Some(x) = arg.get_long() {
-                x.to_string()
-            } else {
-                let mut s = '{'.to_string();
-                s.push_str(arg.id.as_str());
-                s
-            };
-            ord_v.push((arg.get_display_order(), key, arg));
+            let key = (sort_key)(arg);
+            ord_v.push((key, arg));
         }
-        ord_v.sort_by(|a, b| (a.0, &a.1).cmp(&(b.0, &b.1)));
+        ord_v.sort_by(|a, b| a.0.cmp(&b.0));
 
         let next_line_help = self.will_args_wrap(args, longest);
 
-        for (i, (_, _, arg)) in ord_v.iter().enumerate() {
+        for (i, (_, arg)) in ord_v.iter().enumerate() {
             let last_arg = i + 1 == ord_v.len();
             self.write_arg(arg, last_arg, next_line_help, longest);
         }
@@ -786,7 +738,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         let mut first = if !pos.is_empty() {
             // Write positional args if any
             self.warning("ARGS:\n");
-            self.write_args_unsorted(&pos);
+            self.write_args(&pos, "ARGS", positional_sort_key);
             false
         } else {
             true
@@ -797,7 +749,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                 self.none("\n\n");
             }
             self.warning("OPTIONS:\n");
-            self.write_args(&non_pos, "OPTIONS");
+            self.write_args(&non_pos, "OPTIONS", option_sort_key);
             first = false;
         }
         if !custom_headings.is_empty() {
@@ -819,7 +771,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                         self.none("\n\n");
                     }
                     self.warning(format!("{}:\n", heading));
-                    self.write_args(&args, heading);
+                    self.write_args(&args, heading, option_sort_key);
                     first = false
                 }
             }
@@ -1015,10 +967,10 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                     "options" => {
                         // Include even those with a heading as we don't have a good way of
                         // handling help_heading in the template.
-                        self.write_args(&self.cmd.get_non_positionals().collect::<Vec<_>>(), "options");
+                        self.write_args(&self.cmd.get_non_positionals().collect::<Vec<_>>(), "options", option_sort_key);
                     }
                     "positionals" => {
-                        self.write_args(&self.cmd.get_positionals().collect::<Vec<_>>(), "positionals");
+                        self.write_args(&self.cmd.get_positionals().collect::<Vec<_>>(), "positionals", positional_sort_key);
                     }
                     "subcommands" => {
                         self.write_subcommands(self.cmd);
@@ -1035,6 +987,35 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     }
 }
 
+type ArgSortKey = fn(arg: &Arg) -> (usize, String);
+
+fn positional_sort_key(arg: &Arg) -> (usize, String) {
+    (arg.get_index().unwrap_or(0), String::new())
+}
+
+fn option_sort_key(arg: &Arg) -> (usize, String) {
+    // Formatting key like this to ensure that:
+    // 1. Argument has long flags are printed just after short flags.
+    // 2. For two args both have short flags like `-c` and `-C`, the
+    //    `-C` arg is printed just after the `-c` arg
+    // 3. For args without short or long flag, print them at last(sorted
+    //    by arg name).
+    // Example order: -a, -b, -B, -s, --select-file, --select-folder, -x
+
+    let key = if let Some(x) = arg.get_short() {
+        let mut s = x.to_ascii_lowercase().to_string();
+        s.push(if x.is_ascii_lowercase() { '0' } else { '1' });
+        s
+    } else if let Some(x) = arg.get_long() {
+        x.to_string()
+    } else {
+        let mut s = '{'.to_string();
+        s.push_str(arg.id.as_str());
+        s
+    };
+    (arg.get_display_order(), key)
+}
+
 pub(crate) fn dimensions() -> Option<(usize, usize)> {
     #[cfg(not(feature = "wrap_help"))]
     return None;

From 06c40b636ea8304559108c55745d6cc88f1093c7 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 11:33:21 -0500
Subject: [PATCH 12/22] refactor(help): Clarify arg separator

---
 src/output/help.rs | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index 5d4b73bb5b1..6f80cf1cfe6 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -168,13 +168,18 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         let next_line_help = self.will_args_wrap(args, longest);
 
         for (i, (_, arg)) in ord_v.iter().enumerate() {
-            let last_arg = i + 1 == ord_v.len();
-            self.write_arg(arg, last_arg, next_line_help, longest);
+            if i != 0 {
+                self.none("\n");
+                if next_line_help {
+                    self.none("\n");
+                }
+            }
+            self.write_arg(arg, next_line_help, longest);
         }
     }
 
     /// Writes help for an argument to the wrapped stream.
-    fn write_arg(&mut self, arg: &Arg, last_arg: bool, next_line_help: bool, longest: usize) {
+    fn write_arg(&mut self, arg: &Arg, next_line_help: bool, longest: usize) {
         let spec_vals = &self.spec_vals(arg);
 
         self.short(arg);
@@ -193,13 +198,6 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         };
 
         self.help(Some(arg), about, spec_vals, next_line_help, longest);
-
-        if !last_arg {
-            self.none("\n");
-            if next_line_help {
-                self.none("\n");
-            }
-        }
     }
 
     /// Writes argument's short command to the wrapped stream.

From 64753bbc7df1bee91a9eec82ee6c3e76d327a305 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 11:54:34 -0500
Subject: [PATCH 13/22] refactor(help): Make spec value implementations more
 flexible

---
 src/output/help.rs | 27 ++++++++++++++-------------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index 6f80cf1cfe6..76fb71c8cb5 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -368,7 +368,17 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         };
         let mut help = about.clone();
         help.replace_newline();
-        help.none(spec_vals);
+        if !spec_vals.is_empty() {
+            if !help.is_empty() {
+                let sep = if self.use_long && arg.is_some() {
+                    "\n\n"
+                } else {
+                    " "
+                };
+                help.none(sep);
+            }
+            help.none(spec_vals);
+        }
         let avail_chars = self.term_w.saturating_sub(spaces);
         debug!(
             "Help::help: help_width={}, spaces={}, avail={}",
@@ -480,7 +490,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
 
     fn spec_vals(&self, a: &Arg) -> String {
         debug!("Help::spec_vals: a={}", a);
-        let mut spec_vals = vec![];
+        let mut spec_vals = Vec::new();
         #[cfg(feature = "env")]
         if let Some(ref env) = a.env {
             if !a.is_hide_env_set() {
@@ -575,16 +585,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             spec_vals.push(format!("[possible values: {}]", pvs));
         }
         let connector = if self.use_long { "\n" } else { " " };
-        let prefix = if !spec_vals.is_empty() && !a.get_help().unwrap_or_default().is_empty() {
-            if self.use_long {
-                "\n\n"
-            } else {
-                " "
-            }
-        } else {
-            ""
-        };
-        prefix.to_string() + &spec_vals.join(connector)
+        spec_vals.join(connector)
     }
 
     fn write_about(&mut self, before_new_line: bool, after_new_line: bool) {
@@ -677,7 +678,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             let all_als = short_als.join(", ");
 
             if !all_als.is_empty() {
-                spec_vals.push(format!(" [aliases: {}]", all_als));
+                spec_vals.push(format!("[aliases: {}]", all_als));
             }
         }
         spec_vals.join(" ")

From 8607695ed91b0b7f66b9a065208c0d8d81de08ce Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 12:11:27 -0500
Subject: [PATCH 14/22] refactor(help): Simplify the code

While this doesn't reduce size, it cleans things up to make it easier
---
 src/builder/arg.rs     | 23 +++++++++----------
 src/builder/command.rs |  2 +-
 src/output/help.rs     | 50 +++++++++++++++++++-----------------------
 3 files changed, 35 insertions(+), 40 deletions(-)

diff --git a/src/builder/arg.rs b/src/builder/arg.rs
index 3879373ab55..23ffcbf65ed 100644
--- a/src/builder/arg.rs
+++ b/src/builder/arg.rs
@@ -4,7 +4,6 @@ use std::env;
 #[cfg(feature = "env")]
 use std::ffi::OsString;
 use std::{
-    borrow::Cow,
     cmp::{Ord, Ordering},
     fmt::{self, Display, Formatter},
     str,
@@ -3951,26 +3950,28 @@ impl Arg {
     }
 
     // Used for positionals when printing
-    pub(crate) fn name_no_brackets(&self) -> Cow<str> {
+    pub(crate) fn name_no_brackets(&self) -> String {
         debug!("Arg::name_no_brackets:{}", self.get_id());
         let delim = " ";
         if !self.val_names.is_empty() {
             debug!("Arg::name_no_brackets: val_names={:#?}", self.val_names);
 
             if self.val_names.len() > 1 {
-                Cow::Owned(
-                    self.val_names
-                        .iter()
-                        .map(|n| format!("<{}>", n))
-                        .collect::<Vec<_>>()
-                        .join(delim),
-                )
+                self.val_names
+                    .iter()
+                    .map(|n| format!("<{}>", n))
+                    .collect::<Vec<_>>()
+                    .join(delim)
             } else {
-                Cow::Borrowed(self.val_names.first().expect(INTERNAL_ERROR_MSG))
+                self.val_names
+                    .first()
+                    .expect(INTERNAL_ERROR_MSG)
+                    .as_str()
+                    .to_owned()
             }
         } else {
             debug!("Arg::name_no_brackets: just name");
-            Cow::Borrowed(self.get_id().as_str())
+            self.get_id().as_str().to_owned()
         }
     }
 
diff --git a/src/builder/command.rs b/src/builder/command.rs
index 163d1687e6b..f2a8f328db4 100644
--- a/src/builder/command.rs
+++ b/src/builder/command.rs
@@ -4190,7 +4190,7 @@ impl Command {
             .map(|x| {
                 if x.is_positional() {
                     // Print val_name for positional arguments. e.g. <file_name>
-                    x.name_no_brackets().to_string()
+                    x.name_no_brackets()
                 } else {
                     // Print usage string for flags arguments, e.g. <--help>
                     x.to_string()
diff --git a/src/output/help.rs b/src/output/help.rs
index 76fb71c8cb5..c2e43a7c069 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -503,10 +503,11 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                         "={}",
                         env.1
                             .as_ref()
-                            .map_or(Cow::Borrowed(""), |val| val.to_string_lossy())
+                            .map(|s| s.to_string_lossy())
+                            .unwrap_or_default()
                     )
                 } else {
-                    String::new()
+                    Default::default()
                 };
                 let env_info = format!("[env: {}{}]", env.0.to_string_lossy(), env_val);
                 spec_vals.push(env_info);
@@ -534,39 +535,32 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
 
             spec_vals.push(format!("[default: {}]", pvs));
         }
-        if !a.aliases.is_empty() {
-            debug!("Help::spec_vals: Found aliases...{:?}", a.aliases);
 
-            let als = a
-                .aliases
-                .iter()
-                .filter(|&als| als.1) // visible
-                .map(|als| als.0.as_str()) // name
-                .collect::<Vec<_>>()
-                .join(", ");
-
-            if !als.is_empty() {
-                spec_vals.push(format!("[aliases: {}]", als));
-            }
+        let als = a
+            .aliases
+            .iter()
+            .filter(|&als| als.1) // visible
+            .map(|als| als.0.as_str()) // name
+            .collect::<Vec<_>>()
+            .join(", ");
+        if !als.is_empty() {
+            debug!("Help::spec_vals: Found aliases...{:?}", a.aliases);
+            spec_vals.push(format!("[aliases: {}]", als));
         }
 
-        if !a.short_aliases.is_empty() {
+        let als = a
+            .short_aliases
+            .iter()
+            .filter(|&als| als.1) // visible
+            .map(|&als| als.0.to_string()) // name
+            .collect::<Vec<_>>()
+            .join(", ");
+        if !als.is_empty() {
             debug!(
                 "Help::spec_vals: Found short aliases...{:?}",
                 a.short_aliases
             );
-
-            let als = a
-                .short_aliases
-                .iter()
-                .filter(|&als| als.1) // visible
-                .map(|&als| als.0.to_string()) // name
-                .collect::<Vec<_>>()
-                .join(", ");
-
-            if !als.is_empty() {
-                spec_vals.push(format!("[short aliases: {}]", als));
-            }
+            spec_vals.push(format!("[short aliases: {}]", als));
         }
 
         let possible_vals = a.get_possible_values();

From e00abc69050cb2803940f76511d886e3e02062f8 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:01:24 -0500
Subject: [PATCH 15/22] refactor(help): Consolidate arg suffix rendering

This ended up favoring the help implementation
---
 clap_complete/tests/snapshots/basic.bash      |  2 +-
 .../tests/snapshots/feature_sample.bash       |  2 +-
 clap_complete/tests/snapshots/quoting.bash    |  2 +-
 .../tests/snapshots/special_commands.bash     |  2 +-
 .../tests/snapshots/sub_subcommands.bash      |  4 +-
 src/builder/arg.rs                            | 74 +++++++++----------
 src/builder/mod.rs                            |  1 -
 src/output/help.rs                            | 38 +---------
 8 files changed, 45 insertions(+), 80 deletions(-)

diff --git a/clap_complete/tests/snapshots/basic.bash b/clap_complete/tests/snapshots/basic.bash
index eabc9b504d0..d1c4727c6c6 100644
--- a/clap_complete/tests/snapshots/basic.bash
+++ b/clap_complete/tests/snapshots/basic.bash
@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="-c [<SUBCOMMAND>...]"
+            opts="-c <SUBCOMMAND>..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/feature_sample.bash b/clap_complete/tests/snapshots/feature_sample.bash
index caebfbc56d0..925e21aabaa 100644
--- a/clap_complete/tests/snapshots/feature_sample.bash
+++ b/clap_complete/tests/snapshots/feature_sample.bash
@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="<SUBCOMMAND>..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/quoting.bash b/clap_complete/tests/snapshots/quoting.bash
index 80d0c14ed49..a69dd972b5e 100644
--- a/clap_complete/tests/snapshots/quoting.bash
+++ b/clap_complete/tests/snapshots/quoting.bash
@@ -138,7 +138,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="<SUBCOMMAND>..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/special_commands.bash b/clap_complete/tests/snapshots/special_commands.bash
index ef81e2b6329..13b0726c0ee 100644
--- a/clap_complete/tests/snapshots/special_commands.bash
+++ b/clap_complete/tests/snapshots/special_commands.bash
@@ -48,7 +48,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="<SUBCOMMAND>..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/sub_subcommands.bash b/clap_complete/tests/snapshots/sub_subcommands.bash
index be860b1da96..23108c898e9 100644
--- a/clap_complete/tests/snapshots/sub_subcommands.bash
+++ b/clap_complete/tests/snapshots/sub_subcommands.bash
@@ -45,7 +45,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="<SUBCOMMAND>..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -73,7 +73,7 @@ _my-app() {
             return 0
             ;;
         my__app__some_cmd__help)
-            opts="[<SUBCOMMAND>...]"
+            opts="<SUBCOMMAND>..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/src/builder/arg.rs b/src/builder/arg.rs
index 23ffcbf65ed..f8ac113922d 100644
--- a/src/builder/arg.rs
+++ b/src/builder/arg.rs
@@ -3975,6 +3975,40 @@ impl Arg {
         }
     }
 
+    pub(crate) fn stylize_arg_suffix(&self) -> StyledStr {
+        let mut styled = StyledStr::new();
+
+        let mut need_closing_bracket = false;
+        if self.is_takes_value_set() && !self.is_positional() {
+            let is_optional_val = self.get_min_vals() == 0;
+            let sep = if self.is_require_equals_set() {
+                if is_optional_val {
+                    need_closing_bracket = true;
+                    "[="
+                } else {
+                    "="
+                }
+            } else if is_optional_val {
+                need_closing_bracket = true;
+                " ["
+            } else {
+                " "
+            };
+            styled.good(sep);
+        }
+        if self.is_takes_value_set() || self.is_positional() {
+            let arg_val = render_arg_val(self);
+            styled.good(arg_val);
+        } else if matches!(*self.get_action(), ArgAction::Count) {
+            styled.good("...");
+        }
+        if need_closing_bracket {
+            styled.none("]");
+        }
+
+        styled
+    }
+
     /// Either multiple values or occurrences
     pub(crate) fn is_multiple(&self) -> bool {
         self.is_multiple_values_set() || matches!(*self.get_action(), ArgAction::Append)
@@ -4019,41 +4053,7 @@ impl Display for Arg {
         } else if let Some(s) = self.get_short() {
             write!(f, "-{}", s)?;
         }
-        let mut need_closing_bracket = false;
-        let is_optional_val = self.get_min_vals() == 0;
-        if self.is_positional() {
-            if is_optional_val {
-                let sep = "[";
-                need_closing_bracket = true;
-                f.write_str(sep)?;
-            }
-        } else if self.is_takes_value_set() {
-            let sep = if self.is_require_equals_set() {
-                if is_optional_val {
-                    need_closing_bracket = true;
-                    "[="
-                } else {
-                    "="
-                }
-            } else if is_optional_val {
-                need_closing_bracket = true;
-                " ["
-            } else {
-                " "
-            };
-            f.write_str(sep)?;
-        }
-        if self.is_takes_value_set() || self.is_positional() {
-            let arg_val = render_arg_val(self);
-            f.write_str(&arg_val)?;
-        } else if matches!(*self.get_action(), ArgAction::Count) {
-            f.write_str("...")?;
-        }
-        if need_closing_bracket {
-            f.write_str("]")?;
-        }
-
-        Ok(())
+        self.stylize_arg_suffix().fmt(f)
     }
 }
 
@@ -4382,7 +4382,7 @@ mod test {
         let mut p = Arg::new("pos").index(1).num_args(0..);
         p._build();
 
-        assert_eq!(p.to_string(), "[<pos>...]");
+        assert_eq!(p.to_string(), "<pos>...");
     }
 
     #[test]
@@ -4401,7 +4401,7 @@ mod test {
             .action(ArgAction::Set);
         p._build();
 
-        assert_eq!(p.to_string(), "[<pos>]");
+        assert_eq!(p.to_string(), "<pos>");
     }
 
     #[test]
diff --git a/src/builder/mod.rs b/src/builder/mod.rs
index a450cbee408..098ad576e5e 100644
--- a/src/builder/mod.rs
+++ b/src/builder/mod.rs
@@ -57,5 +57,4 @@ pub use value_parser::_AnonymousValueParser;
 #[allow(unused_imports)]
 pub(crate) use self::str::Inner as StrInner;
 pub(crate) use action::CountType;
-pub(crate) use arg::render_arg_val;
 pub(crate) use arg_settings::{ArgFlags, ArgSettings};
diff --git a/src/output/help.rs b/src/output/help.rs
index c2e43a7c069..c742b6b13a4 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -8,12 +8,11 @@ use std::usize;
 use crate::builder::PossibleValue;
 use crate::builder::Str;
 use crate::builder::StyledStr;
-use crate::builder::{render_arg_val, Arg, Command};
+use crate::builder::{Arg, Command};
 use crate::output::display_width;
 use crate::output::wrap;
 use crate::output::Usage;
 use crate::util::FlatSet;
-use crate::ArgAction;
 
 /// `clap` Help Writer.
 ///
@@ -184,7 +183,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
 
         self.short(arg);
         self.long(arg);
-        self.val(arg);
+        self.writer.extend(arg.stylize_arg_suffix().into_iter());
         self.align_to_about(arg, next_line_help, longest);
 
         let about = if self.use_long {
@@ -224,39 +223,6 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         }
     }
 
-    /// Writes argument's possible values to the wrapped stream.
-    fn val(&mut self, arg: &Arg) {
-        debug!("Help::val: arg={}", arg.get_id());
-        let mut need_closing_bracket = false;
-        if arg.is_takes_value_set() && !arg.is_positional() {
-            let is_optional_val = arg.get_min_vals() == 0;
-            let sep = if arg.is_require_equals_set() {
-                if is_optional_val {
-                    need_closing_bracket = true;
-                    "[="
-                } else {
-                    "="
-                }
-            } else if is_optional_val {
-                need_closing_bracket = true;
-                " ["
-            } else {
-                " "
-            };
-            self.none(sep);
-        }
-
-        if arg.is_takes_value_set() || arg.is_positional() {
-            let arg_val = render_arg_val(arg);
-            self.good(arg_val);
-        } else if matches!(*arg.get_action(), ArgAction::Count) {
-            self.good("...");
-        }
-        if need_closing_bracket {
-            self.none("]");
-        }
-    }
-
     /// Write alignment padding between arg's switches/values and its about message.
     fn align_to_about(&mut self, arg: &Arg, next_line_help: bool, longest: usize) {
         debug!(

From 0e0c5eb2180c18829cec149c52d79a2317d0ccda Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:07:32 -0500
Subject: [PATCH 16/22] refactor(help): Consolidate value printing

---
 src/builder/arg.rs | 40 ++++++++++++++++------------------------
 1 file changed, 16 insertions(+), 24 deletions(-)

diff --git a/src/builder/arg.rs b/src/builder/arg.rs
index f8ac113922d..93d8f0834f7 100644
--- a/src/builder/arg.rs
+++ b/src/builder/arg.rs
@@ -4104,42 +4104,34 @@ impl fmt::Debug for Arg {
 pub(crate) fn render_arg_val(arg: &Arg) -> String {
     let mut rendered = String::new();
 
-    let delim = " ";
+    let num_vals = arg.get_num_args().expect(INTERNAL_ERROR_MSG);
 
-    let val_names = if arg.val_names.is_empty() {
+    let mut val_names = if arg.val_names.is_empty() {
         vec![arg.id.as_internal_str().to_owned()]
     } else {
         arg.val_names.clone()
     };
-
-    let mut extra_values = false;
-    debug_assert!(arg.is_takes_value_set());
-    let num_vals = arg.get_num_args().expect(INTERNAL_ERROR_MSG);
     if val_names.len() == 1 {
-        let arg_name = format!("<{}>", val_names[0]);
         let min = num_vals.min_values().max(1);
-        for n in 1..=min {
-            if n != 1 {
-                rendered.push_str(delim);
-            }
-            rendered.push_str(&arg_name);
-        }
-        extra_values |= min < num_vals.max_values();
-    } else {
-        debug_assert!(1 < val_names.len());
-        for (n, val_name) in val_names.iter().enumerate() {
-            let arg_name = format!("<{}>", val_name);
-            if n != 0 {
-                rendered.push_str(delim);
-            }
-            rendered.push_str(&arg_name);
+        let val_name = val_names.pop().unwrap();
+        val_names = vec![val_name; min];
+    }
+
+    debug_assert!(arg.is_takes_value_set());
+    for (n, val_name) in val_names.iter().enumerate() {
+        let arg_name = format!("<{}>", val_name);
+
+        if n != 0 {
+            rendered.push(' ');
         }
-        extra_values |= val_names.len() < num_vals.max_values();
+        rendered.push_str(&arg_name);
     }
+
+    let mut extra_values = false;
+    extra_values |= val_names.len() < num_vals.max_values();
     if arg.is_positional() && matches!(*arg.get_action(), ArgAction::Append) {
         extra_values = true;
     }
-
     if extra_values {
         rendered.push_str("...");
     }

From df7616b82060bf6c08e927b34500e1531c09fddd Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:13:09 -0500
Subject: [PATCH 17/22] fix(help): Match v3 usage for optional positionals

---
 clap_complete/tests/snapshots/basic.bash            |  2 +-
 clap_complete/tests/snapshots/feature_sample.bash   |  2 +-
 clap_complete/tests/snapshots/quoting.bash          |  2 +-
 clap_complete/tests/snapshots/special_commands.bash |  2 +-
 clap_complete/tests/snapshots/sub_subcommands.bash  |  4 ++--
 src/builder/arg.rs                                  | 10 +++++++---
 tests/builder/help.rs                               |  8 ++++----
 7 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/clap_complete/tests/snapshots/basic.bash b/clap_complete/tests/snapshots/basic.bash
index d1c4727c6c6..4690e8b8085 100644
--- a/clap_complete/tests/snapshots/basic.bash
+++ b/clap_complete/tests/snapshots/basic.bash
@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="-c <SUBCOMMAND>..."
+            opts="-c [SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/feature_sample.bash b/clap_complete/tests/snapshots/feature_sample.bash
index 925e21aabaa..260103562e3 100644
--- a/clap_complete/tests/snapshots/feature_sample.bash
+++ b/clap_complete/tests/snapshots/feature_sample.bash
@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/quoting.bash b/clap_complete/tests/snapshots/quoting.bash
index a69dd972b5e..9ede25887c8 100644
--- a/clap_complete/tests/snapshots/quoting.bash
+++ b/clap_complete/tests/snapshots/quoting.bash
@@ -138,7 +138,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/special_commands.bash b/clap_complete/tests/snapshots/special_commands.bash
index 13b0726c0ee..c1b9968748c 100644
--- a/clap_complete/tests/snapshots/special_commands.bash
+++ b/clap_complete/tests/snapshots/special_commands.bash
@@ -48,7 +48,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/clap_complete/tests/snapshots/sub_subcommands.bash b/clap_complete/tests/snapshots/sub_subcommands.bash
index 23108c898e9..73b877c4f5e 100644
--- a/clap_complete/tests/snapshots/sub_subcommands.bash
+++ b/clap_complete/tests/snapshots/sub_subcommands.bash
@@ -45,7 +45,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -73,7 +73,7 @@ _my-app() {
             return 0
             ;;
         my__app__some_cmd__help)
-            opts="<SUBCOMMAND>..."
+            opts="[SUBCOMMAND]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
diff --git a/src/builder/arg.rs b/src/builder/arg.rs
index 93d8f0834f7..79e05943b6f 100644
--- a/src/builder/arg.rs
+++ b/src/builder/arg.rs
@@ -4119,7 +4119,11 @@ pub(crate) fn render_arg_val(arg: &Arg) -> String {
 
     debug_assert!(arg.is_takes_value_set());
     for (n, val_name) in val_names.iter().enumerate() {
-        let arg_name = format!("<{}>", val_name);
+        let arg_name = if arg.is_positional() && num_vals.min_values() == 0 {
+            format!("[{}]", val_name)
+        } else {
+            format!("<{}>", val_name)
+        };
 
         if n != 0 {
             rendered.push(' ');
@@ -4374,7 +4378,7 @@ mod test {
         let mut p = Arg::new("pos").index(1).num_args(0..);
         p._build();
 
-        assert_eq!(p.to_string(), "<pos>...");
+        assert_eq!(p.to_string(), "[pos]...");
     }
 
     #[test]
@@ -4393,7 +4397,7 @@ mod test {
             .action(ArgAction::Set);
         p._build();
 
-        assert_eq!(p.to_string(), "<pos>");
+        assert_eq!(p.to_string(), "[pos]");
     }
 
     #[test]
diff --git a/tests/builder/help.rs b/tests/builder/help.rs
index 61250c6e3ad..11b8d30dd27 100644
--- a/tests/builder/help.rs
+++ b/tests/builder/help.rs
@@ -2065,7 +2065,7 @@ USAGE:
     myapp help [SUBCOMMAND]...
 
 ARGS:
-    <SUBCOMMAND>...    The subcommand whose help message to display
+    [SUBCOMMAND]...    The subcommand whose help message to display
 ";
 
     let cmd = Command::new("myapp")
@@ -2083,7 +2083,7 @@ USAGE:
     myapp subcmd help [SUBCOMMAND]...
 
 ARGS:
-    <SUBCOMMAND>...    The subcommand whose help message to display
+    [SUBCOMMAND]...    The subcommand whose help message to display
 ";
 
     let cmd = Command::new("myapp")
@@ -2569,7 +2569,7 @@ USAGE:
     example help [SUBCOMMAND]...
 
 ARGS:
-    <SUBCOMMAND>...    The subcommand whose help message to display
+    [SUBCOMMAND]...    The subcommand whose help message to display
 ",
         false,
     );
@@ -2612,7 +2612,7 @@ USAGE:
     example help [SUBCOMMAND]...
 
 ARGS:
-    <SUBCOMMAND>...    The subcommand whose help message to display
+    [SUBCOMMAND]...    The subcommand whose help message to display
 ",
         false,
     );

From d652f0348d69f2af9c1f5387e655d326d029edd7 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:15:20 -0500
Subject: [PATCH 18/22] refactor(help): Reduce a fn's visibility

---
 src/builder/arg.rs | 88 +++++++++++++++++++++++-----------------------
 1 file changed, 44 insertions(+), 44 deletions(-)

diff --git a/src/builder/arg.rs b/src/builder/arg.rs
index 79e05943b6f..9758f0ed8c7 100644
--- a/src/builder/arg.rs
+++ b/src/builder/arg.rs
@@ -3997,7 +3997,7 @@ impl Arg {
             styled.good(sep);
         }
         if self.is_takes_value_set() || self.is_positional() {
-            let arg_val = render_arg_val(self);
+            let arg_val = self.render_arg_val();
             styled.good(arg_val);
         } else if matches!(*self.get_action(), ArgAction::Count) {
             styled.good("...");
@@ -4009,6 +4009,49 @@ impl Arg {
         styled
     }
 
+    /// Write the values such as <name1> <name2>
+    fn render_arg_val(&self) -> String {
+        let mut rendered = String::new();
+
+        let num_vals = self.get_num_args().expect(INTERNAL_ERROR_MSG);
+
+        let mut val_names = if self.val_names.is_empty() {
+            vec![self.id.as_internal_str().to_owned()]
+        } else {
+            self.val_names.clone()
+        };
+        if val_names.len() == 1 {
+            let min = num_vals.min_values().max(1);
+            let val_name = val_names.pop().unwrap();
+            val_names = vec![val_name; min];
+        }
+
+        debug_assert!(self.is_takes_value_set());
+        for (n, val_name) in val_names.iter().enumerate() {
+            let arg_name = if self.is_positional() && num_vals.min_values() == 0 {
+                format!("[{}]", val_name)
+            } else {
+                format!("<{}>", val_name)
+            };
+
+            if n != 0 {
+                rendered.push(' ');
+            }
+            rendered.push_str(&arg_name);
+        }
+
+        let mut extra_values = false;
+        extra_values |= val_names.len() < num_vals.max_values();
+        if self.is_positional() && matches!(*self.get_action(), ArgAction::Append) {
+            extra_values = true;
+        }
+        if extra_values {
+            rendered.push_str("...");
+        }
+
+        rendered
+    }
+
     /// Either multiple values or occurrences
     pub(crate) fn is_multiple(&self) -> bool {
         self.is_multiple_values_set() || matches!(*self.get_action(), ArgAction::Append)
@@ -4100,49 +4143,6 @@ impl fmt::Debug for Arg {
     }
 }
 
-/// Write the values such as <name1> <name2>
-pub(crate) fn render_arg_val(arg: &Arg) -> String {
-    let mut rendered = String::new();
-
-    let num_vals = arg.get_num_args().expect(INTERNAL_ERROR_MSG);
-
-    let mut val_names = if arg.val_names.is_empty() {
-        vec![arg.id.as_internal_str().to_owned()]
-    } else {
-        arg.val_names.clone()
-    };
-    if val_names.len() == 1 {
-        let min = num_vals.min_values().max(1);
-        let val_name = val_names.pop().unwrap();
-        val_names = vec![val_name; min];
-    }
-
-    debug_assert!(arg.is_takes_value_set());
-    for (n, val_name) in val_names.iter().enumerate() {
-        let arg_name = if arg.is_positional() && num_vals.min_values() == 0 {
-            format!("[{}]", val_name)
-        } else {
-            format!("<{}>", val_name)
-        };
-
-        if n != 0 {
-            rendered.push(' ');
-        }
-        rendered.push_str(&arg_name);
-    }
-
-    let mut extra_values = false;
-    extra_values |= val_names.len() < num_vals.max_values();
-    if arg.is_positional() && matches!(*arg.get_action(), ArgAction::Append) {
-        extra_values = true;
-    }
-    if extra_values {
-        rendered.push_str("...");
-    }
-
-    rendered
-}
-
 // Flags
 #[cfg(test)]
 mod test {

From 207bb00453e5b0de8f72d0b3d4bb71b4f0d3ac16 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:26:21 -0500
Subject: [PATCH 19/22] refactor(help): Simplify several parts

---
 src/output/help.rs | 32 +++++++++++++-------------------
 1 file changed, 13 insertions(+), 19 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index c742b6b13a4..c2cc6ac33d8 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -181,6 +181,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     fn write_arg(&mut self, arg: &Arg, next_line_help: bool, longest: usize) {
         let spec_vals = &self.spec_vals(arg);
 
+        self.none(TAB);
         self.short(arg);
         self.long(arg);
         self.writer.extend(arg.stylize_arg_suffix().into_iter());
@@ -203,11 +204,9 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     fn short(&mut self, arg: &Arg) {
         debug!("Help::short");
 
-        self.none(TAB);
-
         if let Some(s) = arg.get_short() {
             self.good(format!("-{}", s));
-        } else if !arg.is_positional() {
+        } else if arg.get_long().is_some() {
             self.none(TAB)
         }
     }
@@ -616,7 +615,15 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     fn sc_spec_vals(&self, a: &Command) -> String {
         debug!("Help::sc_spec_vals: a={}", a.get_name());
         let mut spec_vals = vec![];
-        if 0 < a.get_all_aliases().count() || 0 < a.get_all_short_flag_aliases().count() {
+
+        let mut short_als = a
+            .get_visible_short_flag_aliases()
+            .map(|a| format!("-{}", a))
+            .collect::<Vec<_>>();
+        let als = a.get_visible_aliases().map(|s| s.to_string());
+        short_als.extend(als);
+        let all_als = short_als.join(", ");
+        if !all_als.is_empty() {
             debug!(
                 "Help::spec_vals: Found aliases...{:?}",
                 a.get_all_aliases().collect::<Vec<_>>()
@@ -625,22 +632,9 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                 "Help::spec_vals: Found short flag aliases...{:?}",
                 a.get_all_short_flag_aliases().collect::<Vec<_>>()
             );
-
-            let mut short_als = a
-                .get_visible_short_flag_aliases()
-                .map(|a| format!("-{}", a))
-                .collect::<Vec<_>>();
-
-            let als = a.get_visible_aliases().map(|s| s.to_string());
-
-            short_als.extend(als);
-
-            let all_als = short_als.join(", ");
-
-            if !all_als.is_empty() {
-                spec_vals.push(format!("[aliases: {}]", all_als));
-            }
+            spec_vals.push(format!("[aliases: {}]", all_als));
         }
+
         spec_vals.join(" ")
     }
 

From 0c2f20d6602b03569f59f252fd458a77e7afc89d Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:32:08 -0500
Subject: [PATCH 20/22] refactor(help): Drop the parser macro

---
 src/output/help.rs | 53 ++++++++++++++++------------------------------
 1 file changed, 18 insertions(+), 35 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index c2cc6ac33d8..a8ea1d20493 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -843,44 +843,13 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     fn write_templated_help(&mut self, template: &str) {
         debug!("Help::write_templated_help");
 
-        // The strategy is to copy the template from the reader to wrapped stream
-        // until a tag is found. Depending on its value, the appropriate content is copied
-        // to the wrapped stream.
-        // The copy from template is then resumed, repeating this sequence until reading
-        // the complete template.
-
-        macro_rules! tags {
-            (
-                match $part:ident {
-                    $( $tag:expr => $action:stmt )*
-                }
-            ) => {
-                match $part {
-                    $(
-                        part if part.starts_with(concat!($tag, "}")) => {
-                            $action
-                            let rest = &part[$tag.len()+1..];
-                            self.none(rest);
-                        }
-                    )*
-
-                    // Unknown tag, write it back.
-                    part => {
-                        self.none("{");
-                        self.none(part);
-                    }
-                }
-            };
-        }
-
         let mut parts = template.split('{');
         if let Some(first) = parts.next() {
             self.none(first);
         }
-
         for part in parts {
-            tags! {
-                match part {
+            if let Some((tag, rest)) = part.split_once('}') {
+                match tag {
                     "name" => {
                         self.write_display_name();
                     }
@@ -920,10 +889,18 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                     "options" => {
                         // Include even those with a heading as we don't have a good way of
                         // handling help_heading in the template.
-                        self.write_args(&self.cmd.get_non_positionals().collect::<Vec<_>>(), "options", option_sort_key);
+                        self.write_args(
+                            &self.cmd.get_non_positionals().collect::<Vec<_>>(),
+                            "options",
+                            option_sort_key,
+                        );
                     }
                     "positionals" => {
-                        self.write_args(&self.cmd.get_positionals().collect::<Vec<_>>(), "positionals", positional_sort_key);
+                        self.write_args(
+                            &self.cmd.get_positionals().collect::<Vec<_>>(),
+                            "positionals",
+                            positional_sort_key,
+                        );
                     }
                     "subcommands" => {
                         self.write_subcommands(self.cmd);
@@ -934,7 +911,13 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                     "before-help" => {
                         self.write_before_help();
                     }
+                    _ => {
+                        self.none("{");
+                        self.none(tag);
+                        self.none("}");
+                    }
                 }
+                self.none(rest);
             }
         }
     }

From 81f29d29ad1e66a3044a503dc8910d75d48262ef Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:39:21 -0500
Subject: [PATCH 21/22] refactor(help): Top-down sort functions

---
 src/output/help.rs | 789 ++++++++++++++++++++++-----------------------
 1 file changed, 394 insertions(+), 395 deletions(-)

diff --git a/src/output/help.rs b/src/output/help.rs
index a8ea1d20493..a96913bd557 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -110,32 +110,291 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
     }
 }
 
-// Methods to write Arg help.
+// Template
 impl<'cmd, 'writer> Help<'cmd, 'writer> {
-    fn extend(&mut self, msg: &StyledStr) {
-        self.writer.extend(msg.iter());
+    /// Write help to stream for the parser in the format defined by the template.
+    ///
+    /// For details about the template language see [`Command::help_template`].
+    ///
+    /// [`Command::help_template`]: Command::help_template()
+    fn write_templated_help(&mut self, template: &str) {
+        debug!("Help::write_templated_help");
+
+        let mut parts = template.split('{');
+        if let Some(first) = parts.next() {
+            self.none(first);
+        }
+        for part in parts {
+            if let Some((tag, rest)) = part.split_once('}') {
+                match tag {
+                    "name" => {
+                        self.write_display_name();
+                    }
+                    "bin" => {
+                        self.write_bin_name();
+                    }
+                    "version" => {
+                        self.write_version();
+                    }
+                    "author" => {
+                        self.write_author(false, false);
+                    }
+                    "author-with-newline" => {
+                        self.write_author(false, true);
+                    }
+                    "author-section" => {
+                        self.write_author(true, true);
+                    }
+                    "about" => {
+                        self.write_about(false, false);
+                    }
+                    "about-with-newline" => {
+                        self.write_about(false, true);
+                    }
+                    "about-section" => {
+                        self.write_about(true, true);
+                    }
+                    "usage-heading" => {
+                        self.warning("USAGE:");
+                    }
+                    "usage" => {
+                        self.none(self.usage.create_usage_no_title(&[]));
+                    }
+                    "all-args" => {
+                        self.write_all_args();
+                    }
+                    "options" => {
+                        // Include even those with a heading as we don't have a good way of
+                        // handling help_heading in the template.
+                        self.write_args(
+                            &self.cmd.get_non_positionals().collect::<Vec<_>>(),
+                            "options",
+                            option_sort_key,
+                        );
+                    }
+                    "positionals" => {
+                        self.write_args(
+                            &self.cmd.get_positionals().collect::<Vec<_>>(),
+                            "positionals",
+                            positional_sort_key,
+                        );
+                    }
+                    "subcommands" => {
+                        self.write_subcommands(self.cmd);
+                    }
+                    "after-help" => {
+                        self.write_after_help();
+                    }
+                    "before-help" => {
+                        self.write_before_help();
+                    }
+                    _ => {
+                        self.none("{");
+                        self.none(tag);
+                        self.none("}");
+                    }
+                }
+                self.none(rest);
+            }
+        }
     }
+}
 
-    fn good<T: Into<String>>(&mut self, msg: T) {
-        self.writer.good(msg);
+/// Basic template methods
+impl<'cmd, 'writer> Help<'cmd, 'writer> {
+    /// Writes binary name of a Parser Object to the wrapped stream.
+    fn write_display_name(&mut self) {
+        debug!("Help::write_display_name");
+
+        let display_name = wrap(
+            &self
+                .cmd
+                .get_display_name()
+                .unwrap_or_else(|| self.cmd.get_name())
+                .replace("{n}", "\n"),
+            self.term_w,
+        );
+        self.good(&display_name);
     }
 
-    fn warning<T: Into<String>>(&mut self, msg: T) {
-        self.writer.warning(msg);
+    /// Writes binary name of a Parser Object to the wrapped stream.
+    fn write_bin_name(&mut self) {
+        debug!("Help::write_bin_name");
+
+        let bin_name = if let Some(bn) = self.cmd.get_bin_name() {
+            if bn.contains(' ') {
+                // In case we're dealing with subcommands i.e. git mv is translated to git-mv
+                bn.replace(' ', "-")
+            } else {
+                wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
+            }
+        } else {
+            wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
+        };
+        self.good(&bin_name);
     }
 
-    fn none<T: Into<String>>(&mut self, msg: T) {
-        self.writer.none(msg);
+    fn write_version(&mut self) {
+        let version = self
+            .cmd
+            .get_version()
+            .or_else(|| self.cmd.get_long_version());
+        if let Some(output) = version {
+            self.none(wrap(output, self.term_w));
+        }
     }
 
-    fn get_spaces(&self, n: usize) -> String {
-        " ".repeat(n)
+    fn write_author(&mut self, before_new_line: bool, after_new_line: bool) {
+        if let Some(author) = self.cmd.get_author() {
+            if before_new_line {
+                self.none("\n");
+            }
+            self.none(wrap(author, self.term_w));
+            if after_new_line {
+                self.none("\n");
+            }
+        }
+    }
+
+    fn write_about(&mut self, before_new_line: bool, after_new_line: bool) {
+        let about = if self.use_long {
+            self.cmd.get_long_about().or_else(|| self.cmd.get_about())
+        } else {
+            self.cmd.get_about()
+        };
+        if let Some(output) = about {
+            if before_new_line {
+                self.none("\n");
+            }
+            let mut output = output.clone();
+            output.replace_newline();
+            output.wrap(self.term_w);
+            self.writer.extend(output.into_iter());
+            if after_new_line {
+                self.none("\n");
+            }
+        }
     }
 
-    fn spaces(&mut self, n: usize) {
-        self.none(self.get_spaces(n));
-    }
+    fn write_before_help(&mut self) {
+        debug!("Help::write_before_help");
+        let before_help = if self.use_long {
+            self.cmd
+                .get_before_long_help()
+                .or_else(|| self.cmd.get_before_help())
+        } else {
+            self.cmd.get_before_help()
+        };
+        if let Some(output) = before_help {
+            let mut output = output.clone();
+            output.replace_newline();
+            output.wrap(self.term_w);
+            self.writer.extend(output.into_iter());
+            self.none("\n\n");
+        }
+    }
+
+    fn write_after_help(&mut self) {
+        debug!("Help::write_after_help");
+        let after_help = if self.use_long {
+            self.cmd
+                .get_after_long_help()
+                .or_else(|| self.cmd.get_after_help())
+        } else {
+            self.cmd.get_after_help()
+        };
+        if let Some(output) = after_help {
+            self.none("\n\n");
+            let mut output = output.clone();
+            output.replace_newline();
+            output.wrap(self.term_w);
+            self.writer.extend(output.into_iter());
+        }
+    }
+}
+
+/// Arg handling
+impl<'cmd, 'writer> Help<'cmd, 'writer> {
+    /// Writes help for all arguments (options, flags, args, subcommands)
+    /// including titles of a Parser Object to the wrapped stream.
+    pub(crate) fn write_all_args(&mut self) {
+        debug!("Help::write_all_args");
+        let pos = self
+            .cmd
+            .get_positionals_with_no_heading()
+            .filter(|arg| should_show_arg(self.use_long, arg))
+            .collect::<Vec<_>>();
+        let non_pos = self
+            .cmd
+            .get_non_positionals_with_no_heading()
+            .filter(|arg| should_show_arg(self.use_long, arg))
+            .collect::<Vec<_>>();
+        let subcmds = self.cmd.has_visible_subcommands();
+
+        let custom_headings = self
+            .cmd
+            .get_arguments()
+            .filter_map(|arg| arg.get_help_heading())
+            .collect::<FlatSet<_>>();
+
+        let mut first = if !pos.is_empty() {
+            // Write positional args if any
+            self.warning("ARGS:\n");
+            self.write_args(&pos, "ARGS", positional_sort_key);
+            false
+        } else {
+            true
+        };
+
+        if !non_pos.is_empty() {
+            if !first {
+                self.none("\n\n");
+            }
+            self.warning("OPTIONS:\n");
+            self.write_args(&non_pos, "OPTIONS", option_sort_key);
+            first = false;
+        }
+        if !custom_headings.is_empty() {
+            for heading in custom_headings {
+                let args = self
+                    .cmd
+                    .get_arguments()
+                    .filter(|a| {
+                        if let Some(help_heading) = a.get_help_heading() {
+                            return help_heading == heading;
+                        }
+                        false
+                    })
+                    .filter(|arg| should_show_arg(self.use_long, arg))
+                    .collect::<Vec<_>>();
+
+                if !args.is_empty() {
+                    if !first {
+                        self.none("\n\n");
+                    }
+                    self.warning(format!("{}:\n", heading));
+                    self.write_args(&args, heading, option_sort_key);
+                    first = false
+                }
+            }
+        }
+
+        if subcmds {
+            if !first {
+                self.none("\n\n");
+            }
+
+            let default_help_heading = Str::from("SUBCOMMANDS");
+            self.warning(
+                self.cmd
+                    .get_subcommand_help_heading()
+                    .unwrap_or(&default_help_heading),
+            );
+            self.warning(":\n");
 
+            self.write_subcommands(self.cmd);
+        }
+    }
     /// Sorts arguments by length and display order and write their help to the wrapped stream.
     fn write_args(&mut self, args: &[&Arg], _category: &str, sort_key: ArgSortKey) {
         debug!("Help::write_args {}", _category);
@@ -264,42 +523,6 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         }
     }
 
-    fn write_before_help(&mut self) {
-        debug!("Help::write_before_help");
-        let before_help = if self.use_long {
-            self.cmd
-                .get_before_long_help()
-                .or_else(|| self.cmd.get_before_help())
-        } else {
-            self.cmd.get_before_help()
-        };
-        if let Some(output) = before_help {
-            let mut output = output.clone();
-            output.replace_newline();
-            output.wrap(self.term_w);
-            self.writer.extend(output.into_iter());
-            self.none("\n\n");
-        }
-    }
-
-    fn write_after_help(&mut self) {
-        debug!("Help::write_after_help");
-        let after_help = if self.use_long {
-            self.cmd
-                .get_after_long_help()
-                .or_else(|| self.cmd.get_after_help())
-        } else {
-            self.cmd.get_after_help()
-        };
-        if let Some(output) = after_help {
-            self.none("\n\n");
-            let mut output = output.clone();
-            output.replace_newline();
-            output.wrap(self.term_w);
-            self.writer.extend(output.into_iter());
-        }
-    }
-
     /// Writes argument's help to the wrapped stream.
     fn help(
         &mut self,
@@ -520,248 +743,60 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
             .map(|&als| als.0.to_string()) // name
             .collect::<Vec<_>>()
             .join(", ");
-        if !als.is_empty() {
-            debug!(
-                "Help::spec_vals: Found short aliases...{:?}",
-                a.short_aliases
-            );
-            spec_vals.push(format!("[short aliases: {}]", als));
-        }
-
-        let possible_vals = a.get_possible_values();
-        if !(a.is_hide_possible_values_set()
-            || possible_vals.is_empty()
-            || self.use_long && possible_vals.iter().any(PossibleValue::should_show_help))
-        {
-            debug!("Help::spec_vals: Found possible vals...{:?}", possible_vals);
-
-            let pvs = possible_vals
-                .iter()
-                .filter_map(PossibleValue::get_visible_quoted_name)
-                .collect::<Vec<_>>()
-                .join(", ");
-
-            spec_vals.push(format!("[possible values: {}]", pvs));
-        }
-        let connector = if self.use_long { "\n" } else { " " };
-        spec_vals.join(connector)
-    }
-
-    fn write_about(&mut self, before_new_line: bool, after_new_line: bool) {
-        let about = if self.use_long {
-            self.cmd.get_long_about().or_else(|| self.cmd.get_about())
-        } else {
-            self.cmd.get_about()
-        };
-        if let Some(output) = about {
-            if before_new_line {
-                self.none("\n");
-            }
-            let mut output = output.clone();
-            output.replace_newline();
-            output.wrap(self.term_w);
-            self.writer.extend(output.into_iter());
-            if after_new_line {
-                self.none("\n");
-            }
-        }
-    }
-
-    fn write_author(&mut self, before_new_line: bool, after_new_line: bool) {
-        if let Some(author) = self.cmd.get_author() {
-            if before_new_line {
-                self.none("\n");
-            }
-            self.none(wrap(author, self.term_w));
-            if after_new_line {
-                self.none("\n");
-            }
-        }
-    }
-
-    fn write_version(&mut self) {
-        let version = self
-            .cmd
-            .get_version()
-            .or_else(|| self.cmd.get_long_version());
-        if let Some(output) = version {
-            self.none(wrap(output, self.term_w));
-        }
-    }
-}
-
-/// Methods to write a single subcommand
-impl<'cmd, 'writer> Help<'cmd, 'writer> {
-    fn write_subcommand(
-        &mut self,
-        sc_str: &str,
-        cmd: &Command,
-        next_line_help: bool,
-        longest: usize,
-    ) {
-        debug!("Help::write_subcommand");
-
-        let spec_vals = &self.sc_spec_vals(cmd);
-
-        let about = cmd
-            .get_about()
-            .or_else(|| cmd.get_long_about())
-            .unwrap_or_default();
-
-        self.subcmd(sc_str, next_line_help, longest);
-        self.help(None, about, spec_vals, next_line_help, longest)
-    }
-
-    fn sc_spec_vals(&self, a: &Command) -> String {
-        debug!("Help::sc_spec_vals: a={}", a.get_name());
-        let mut spec_vals = vec![];
-
-        let mut short_als = a
-            .get_visible_short_flag_aliases()
-            .map(|a| format!("-{}", a))
-            .collect::<Vec<_>>();
-        let als = a.get_visible_aliases().map(|s| s.to_string());
-        short_als.extend(als);
-        let all_als = short_als.join(", ");
-        if !all_als.is_empty() {
-            debug!(
-                "Help::spec_vals: Found aliases...{:?}",
-                a.get_all_aliases().collect::<Vec<_>>()
-            );
-            debug!(
-                "Help::spec_vals: Found short flag aliases...{:?}",
-                a.get_all_short_flag_aliases().collect::<Vec<_>>()
-            );
-            spec_vals.push(format!("[aliases: {}]", all_als));
-        }
-
-        spec_vals.join(" ")
-    }
-
-    fn subcommand_next_line_help(&self, cmd: &Command, spec_vals: &str, longest: usize) -> bool {
-        if self.next_line_help | self.use_long {
-            // setting_next_line
-            true
-        } else {
-            // force_next_line
-            let h = cmd.get_about().unwrap_or_default();
-            let h_w = h.display_width() + display_width(spec_vals);
-            let taken = longest + 12;
-            self.term_w >= taken
-                && (taken as f32 / self.term_w as f32) > 0.40
-                && h_w > (self.term_w - taken)
-        }
-    }
-
-    /// Writes subcommand to the wrapped stream.
-    fn subcmd(&mut self, sc_str: &str, next_line_help: bool, longest: usize) {
-        self.none(TAB);
-        self.good(sc_str);
-        if !next_line_help {
-            let width = display_width(sc_str);
-            self.spaces(width.max(longest + 4) - width);
-        }
-    }
-}
-
-// Methods to write Parser help.
-impl<'cmd, 'writer> Help<'cmd, 'writer> {
-    /// Writes help for all arguments (options, flags, args, subcommands)
-    /// including titles of a Parser Object to the wrapped stream.
-    pub(crate) fn write_all_args(&mut self) {
-        debug!("Help::write_all_args");
-        let pos = self
-            .cmd
-            .get_positionals_with_no_heading()
-            .filter(|arg| should_show_arg(self.use_long, arg))
-            .collect::<Vec<_>>();
-        let non_pos = self
-            .cmd
-            .get_non_positionals_with_no_heading()
-            .filter(|arg| should_show_arg(self.use_long, arg))
-            .collect::<Vec<_>>();
-        let subcmds = self.cmd.has_visible_subcommands();
-
-        let custom_headings = self
-            .cmd
-            .get_arguments()
-            .filter_map(|arg| arg.get_help_heading())
-            .collect::<FlatSet<_>>();
-
-        let mut first = if !pos.is_empty() {
-            // Write positional args if any
-            self.warning("ARGS:\n");
-            self.write_args(&pos, "ARGS", positional_sort_key);
-            false
-        } else {
-            true
-        };
-
-        if !non_pos.is_empty() {
-            if !first {
-                self.none("\n\n");
-            }
-            self.warning("OPTIONS:\n");
-            self.write_args(&non_pos, "OPTIONS", option_sort_key);
-            first = false;
-        }
-        if !custom_headings.is_empty() {
-            for heading in custom_headings {
-                let args = self
-                    .cmd
-                    .get_arguments()
-                    .filter(|a| {
-                        if let Some(help_heading) = a.get_help_heading() {
-                            return help_heading == heading;
-                        }
-                        false
-                    })
-                    .filter(|arg| should_show_arg(self.use_long, arg))
-                    .collect::<Vec<_>>();
-
-                if !args.is_empty() {
-                    if !first {
-                        self.none("\n\n");
-                    }
-                    self.warning(format!("{}:\n", heading));
-                    self.write_args(&args, heading, option_sort_key);
-                    first = false
-                }
-            }
+        if !als.is_empty() {
+            debug!(
+                "Help::spec_vals: Found short aliases...{:?}",
+                a.short_aliases
+            );
+            spec_vals.push(format!("[short aliases: {}]", als));
         }
 
-        if subcmds {
-            if !first {
-                self.none("\n\n");
-            }
+        let possible_vals = a.get_possible_values();
+        if !(a.is_hide_possible_values_set()
+            || possible_vals.is_empty()
+            || self.use_long && possible_vals.iter().any(PossibleValue::should_show_help))
+        {
+            debug!("Help::spec_vals: Found possible vals...{:?}", possible_vals);
 
-            let default_help_heading = Str::from("SUBCOMMANDS");
-            self.warning(
-                self.cmd
-                    .get_subcommand_help_heading()
-                    .unwrap_or(&default_help_heading),
-            );
-            self.warning(":\n");
+            let pvs = possible_vals
+                .iter()
+                .filter_map(PossibleValue::get_visible_quoted_name)
+                .collect::<Vec<_>>()
+                .join(", ");
 
-            self.write_subcommands(self.cmd);
+            spec_vals.push(format!("[possible values: {}]", pvs));
         }
+        let connector = if self.use_long { "\n" } else { " " };
+        spec_vals.join(connector)
     }
 
-    /// Will use next line help on writing subcommands.
-    fn will_subcommands_wrap<'a>(
-        &self,
-        subcommands: impl IntoIterator<Item = &'a Command>,
-        longest: usize,
-    ) -> bool {
-        subcommands
-            .into_iter()
-            .filter(|&subcommand| should_show_subcommand(subcommand))
-            .any(|subcommand| {
-                let spec_vals = &self.sc_spec_vals(subcommand);
-                self.subcommand_next_line_help(subcommand, spec_vals, longest)
-            })
+    fn extend(&mut self, msg: &StyledStr) {
+        self.writer.extend(msg.iter());
+    }
+
+    fn good<T: Into<String>>(&mut self, msg: T) {
+        self.writer.good(msg);
+    }
+
+    fn warning<T: Into<String>>(&mut self, msg: T) {
+        self.writer.warning(msg);
+    }
+
+    fn none<T: Into<String>>(&mut self, msg: T) {
+        self.writer.none(msg);
+    }
+
+    fn get_spaces(&self, n: usize) -> String {
+        " ".repeat(n)
+    }
+
+    fn spaces(&mut self, n: usize) {
+        self.none(self.get_spaces(n));
     }
+}
 
+/// Subcommand handling
+impl<'cmd, 'writer> Help<'cmd, 'writer> {
     /// Writes help for subcommands of a Parser Object to the wrapped stream.
     fn write_subcommands(&mut self, cmd: &Command) {
         debug!("Help::write_subcommands");
@@ -800,125 +835,89 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
         }
     }
 
-    /// Writes binary name of a Parser Object to the wrapped stream.
-    fn write_display_name(&mut self) {
-        debug!("Help::write_display_name");
-
-        let display_name = wrap(
-            &self
-                .cmd
-                .get_display_name()
-                .unwrap_or_else(|| self.cmd.get_name())
-                .replace("{n}", "\n"),
-            self.term_w,
-        );
-        self.good(&display_name);
+    /// Will use next line help on writing subcommands.
+    fn will_subcommands_wrap<'a>(
+        &self,
+        subcommands: impl IntoIterator<Item = &'a Command>,
+        longest: usize,
+    ) -> bool {
+        subcommands
+            .into_iter()
+            .filter(|&subcommand| should_show_subcommand(subcommand))
+            .any(|subcommand| {
+                let spec_vals = &self.sc_spec_vals(subcommand);
+                self.subcommand_next_line_help(subcommand, spec_vals, longest)
+            })
     }
 
-    /// Writes binary name of a Parser Object to the wrapped stream.
-    fn write_bin_name(&mut self) {
-        debug!("Help::write_bin_name");
+    fn write_subcommand(
+        &mut self,
+        sc_str: &str,
+        cmd: &Command,
+        next_line_help: bool,
+        longest: usize,
+    ) {
+        debug!("Help::write_subcommand");
 
-        let bin_name = if let Some(bn) = self.cmd.get_bin_name() {
-            if bn.contains(' ') {
-                // In case we're dealing with subcommands i.e. git mv is translated to git-mv
-                bn.replace(' ', "-")
-            } else {
-                wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
-            }
-        } else {
-            wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w)
-        };
-        self.good(&bin_name);
+        let spec_vals = &self.sc_spec_vals(cmd);
+
+        let about = cmd
+            .get_about()
+            .or_else(|| cmd.get_long_about())
+            .unwrap_or_default();
+
+        self.subcmd(sc_str, next_line_help, longest);
+        self.help(None, about, spec_vals, next_line_help, longest)
     }
-}
 
-// Methods to write Parser help using templates.
-impl<'cmd, 'writer> Help<'cmd, 'writer> {
-    /// Write help to stream for the parser in the format defined by the template.
-    ///
-    /// For details about the template language see [`Command::help_template`].
-    ///
-    /// [`Command::help_template`]: Command::help_template()
-    fn write_templated_help(&mut self, template: &str) {
-        debug!("Help::write_templated_help");
+    fn sc_spec_vals(&self, a: &Command) -> String {
+        debug!("Help::sc_spec_vals: a={}", a.get_name());
+        let mut spec_vals = vec![];
 
-        let mut parts = template.split('{');
-        if let Some(first) = parts.next() {
-            self.none(first);
+        let mut short_als = a
+            .get_visible_short_flag_aliases()
+            .map(|a| format!("-{}", a))
+            .collect::<Vec<_>>();
+        let als = a.get_visible_aliases().map(|s| s.to_string());
+        short_als.extend(als);
+        let all_als = short_als.join(", ");
+        if !all_als.is_empty() {
+            debug!(
+                "Help::spec_vals: Found aliases...{:?}",
+                a.get_all_aliases().collect::<Vec<_>>()
+            );
+            debug!(
+                "Help::spec_vals: Found short flag aliases...{:?}",
+                a.get_all_short_flag_aliases().collect::<Vec<_>>()
+            );
+            spec_vals.push(format!("[aliases: {}]", all_als));
         }
-        for part in parts {
-            if let Some((tag, rest)) = part.split_once('}') {
-                match tag {
-                    "name" => {
-                        self.write_display_name();
-                    }
-                    "bin" => {
-                        self.write_bin_name();
-                    }
-                    "version" => {
-                        self.write_version();
-                    }
-                    "author" => {
-                        self.write_author(false, false);
-                    }
-                    "author-with-newline" => {
-                        self.write_author(false, true);
-                    }
-                    "author-section" => {
-                        self.write_author(true, true);
-                    }
-                    "about" => {
-                        self.write_about(false, false);
-                    }
-                    "about-with-newline" => {
-                        self.write_about(false, true);
-                    }
-                    "about-section" => {
-                        self.write_about(true, true);
-                    }
-                    "usage-heading" => {
-                        self.warning("USAGE:");
-                    }
-                    "usage" => {
-                        self.none(self.usage.create_usage_no_title(&[]));
-                    }
-                    "all-args" => {
-                        self.write_all_args();
-                    }
-                    "options" => {
-                        // Include even those with a heading as we don't have a good way of
-                        // handling help_heading in the template.
-                        self.write_args(
-                            &self.cmd.get_non_positionals().collect::<Vec<_>>(),
-                            "options",
-                            option_sort_key,
-                        );
-                    }
-                    "positionals" => {
-                        self.write_args(
-                            &self.cmd.get_positionals().collect::<Vec<_>>(),
-                            "positionals",
-                            positional_sort_key,
-                        );
-                    }
-                    "subcommands" => {
-                        self.write_subcommands(self.cmd);
-                    }
-                    "after-help" => {
-                        self.write_after_help();
-                    }
-                    "before-help" => {
-                        self.write_before_help();
-                    }
-                    _ => {
-                        self.none("{");
-                        self.none(tag);
-                        self.none("}");
-                    }
-                }
-                self.none(rest);
-            }
+
+        spec_vals.join(" ")
+    }
+
+    fn subcommand_next_line_help(&self, cmd: &Command, spec_vals: &str, longest: usize) -> bool {
+        if self.next_line_help | self.use_long {
+            // setting_next_line
+            true
+        } else {
+            // force_next_line
+            let h = cmd.get_about().unwrap_or_default();
+            let h_w = h.display_width() + display_width(spec_vals);
+            let taken = longest + 12;
+            self.term_w >= taken
+                && (taken as f32 / self.term_w as f32) > 0.40
+                && h_w > (self.term_w - taken)
+        }
+    }
+
+    /// Writes subcommand to the wrapped stream.
+    fn subcmd(&mut self, sc_str: &str, next_line_help: bool, longest: usize) {
+        self.none(TAB);
+        self.good(sc_str);
+        if !next_line_help {
+            let width = display_width(sc_str);
+            self.spaces(width.max(longest + 4) - width);
         }
     }
 }

From 8382675985479dee0494b32d43ceca31df86c9f7 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 25 Aug 2022 13:45:36 -0500
Subject: [PATCH 22/22] style: Fix a typo

---
 src/output/textwrap/core.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/output/textwrap/core.rs b/src/output/textwrap/core.rs
index dac98d55289..793ae69e12e 100644
--- a/src/output/textwrap/core.rs
+++ b/src/output/textwrap/core.rs
@@ -13,7 +13,7 @@
 /// ## Emojis and CJK Characters
 ///
 /// Characters such as emojis and [CJK characters] used in the
-/// Chinese, Japanese, and Korean langauges are seen as double-width,
+/// Chinese, Japanese, and Korean languages are seen as double-width,
 /// even if the `unicode-width` feature is disabled:
 ///
 /// # Limitations