From 4d2cc9b3e1c3d0bb66c2a18210ee05ce13327444 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 ++++++++++++++++++++++++++++++++++++++
 Cargo.toml                |  1 +
 src/builder/styled_str.rs | 19 +++++++++++++++++--
 3 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 1a6961b4ba22..c1732008aa59 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -183,6 +183,7 @@ dependencies = [
  "bitflags",
  "clap_derive",
  "clap_lex 0.3.3",
+ "color-print",
  "humantime",
  "once_cell",
  "rustversion",
@@ -267,6 +268,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",
+]
+
 [[package]]
 name = "concolor-override"
 version = "1.0.0"
@@ -568,6 +590,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"
@@ -577,6 +605,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/Cargo.toml b/Cargo.toml
index 231402a99e75..8d18dc93696e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -114,6 +114,7 @@ snapbox = "0.4.10"
 shlex = "1.1.0"
 static_assertions = "1.1.0"
 unic-emoji-char = "0.9.0"
+color-print = "0.3.4"
 
 [[example]]
 name = "demo"
diff --git a/src/builder/styled_str.rs b/src/builder/styled_str.rs
index cf52ab589f03..2e974952a57d 100644
--- a/src/builder/styled_str.rs
+++ b/src/builder/styled_str.rs
@@ -1,7 +1,22 @@
 /// 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
+/// // `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);