From b6432c8eadae969544dca6e9b2e09f1457c72472 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 16 Mar 2023 15:11:12 -0500
Subject: [PATCH] docs(help): Show how to style text

Fixes #3108
Fixes #1433
---
 Cargo.lock                             | 38 ++++++++++++++++++++++++++
 clap_builder/Cargo.toml                |  1 +
 clap_builder/src/builder/styled_str.rs | 20 ++++++++++++--
 3 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 180285324e0..6d3fa11539d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -208,6 +208,7 @@ dependencies = [
  "backtrace",
  "bitflags",
  "clap_lex 0.4.0",
+ "color-print",
  "humantime",
  "once_cell",
  "rustversion",
@@ -278,6 +279,27 @@ dependencies = [
  "snapbox",
 ]
 
+[[package]]
+name = "color-print"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2a5e6504ed8648554968650feecea00557a3476bc040d0ffc33080e66b646d0"
+dependencies = [
+ "color-print-proc-macro",
+]
+
+[[package]]
+name = "color-print-proc-macro"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d51beaa537d73d2d1ff34ee70bc095f170420ab2ec5d687ecd3ec2b0d092514b"
+dependencies = [
+ "nom",
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "concolor-override"
 version = "1.0.0"
@@ -579,6 +601,12 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
 [[package]]
 name = "miniz_oxide"
 version = "0.6.2"
@@ -588,6 +616,16 @@ dependencies = [
  "adler",
 ]
 
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
 [[package]]
 name = "normalize-line-endings"
 version = "0.3.0"
diff --git a/clap_builder/Cargo.toml b/clap_builder/Cargo.toml
index 98e2ad8689f..85f5bb765dc 100644
--- a/clap_builder/Cargo.toml
+++ b/clap_builder/Cargo.toml
@@ -80,3 +80,4 @@ snapbox = "0.4.10"
 shlex = "1.1.0"
 static_assertions = "1.1.0"
 unic-emoji-char = "0.9.0"
+color-print = "0.3.4"
diff --git a/clap_builder/src/builder/styled_str.rs b/clap_builder/src/builder/styled_str.rs
index cf52ab589f0..94c838aaabc 100644
--- a/clap_builder/src/builder/styled_str.rs
+++ b/clap_builder/src/builder/styled_str.rs
@@ -1,7 +1,23 @@
 /// Terminal-styling container
 ///
-/// For now, this is the same as a [`Str`][crate::builder::Str].  This exists to reserve space in
-/// the API for exposing terminal styling.
+/// Styling may be encoded as [ANSI Escape Code](https://en.wikipedia.org/wiki/ANSI_escape_code)
+///
+/// # Examples
+///
+/// ```rust
+/// # use clap_builder as clap;
+/// // `cstr!` converts tags to ANSI codes
+/// let after_help: &'static str = color_print::cstr!(
+/// r#"<bold><underline>Examples</underline></bold>
+///
+///   <dim>$</dim> <bold>mybin --input file.toml</bold>
+/// "#);
+///
+/// let cmd = clap::Command::new("mybin")
+///     .after_help(after_help)  // The `&str` gets converted into a `StyledStr`
+///     // ...
+/// #   ;
+/// ```
 #[derive(Clone, Default, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct StyledStr(String);