From 0b2345a46fca828d9da998069d7d6b6500f11f60 Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@wezfurlong.org>
Date: Sun, 5 Feb 2023 13:44:17 -0700
Subject: [PATCH] docs: expand wezterm.format examples

refs: https://github.com/wez/wezterm/issues/3056
---
 docs/config/lua/wezterm/format.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/config/lua/wezterm/format.md b/docs/config/lua/wezterm/format.md
index ac5d3903f..aeb7d4b27 100644
--- a/docs/config/lua/wezterm/format.md
+++ b/docs/config/lua/wezterm/format.md
@@ -30,7 +30,9 @@ wezterm.log_info(wezterm.format {
 
 Possible values for the `FormatItem` elements are:
 
-* `{Text="Hello"}` - the text `Hello`. The string can be any string expression.
+* `{Text="Hello"}` - the text `Hello`. The string can be any string expression,
+  including escape sequences that are not supported directly by
+  `wezterm.format`.
 * `{Attribute={Underline="None"}}` - disable underline
 * `{Attribute={Underline="Single"}}` - enable single underline
 * `{Attribute={Underline="Double"}}` - enable double underline
@@ -47,3 +49,17 @@ Possible values for the `FormatItem` elements are:
 * `{Background={AnsiColor="Black"}}` - set the background color to an ansi color as per `Foreground` above.
 * `{Background={Color="blue"}}` - set the background color to a named color or rgb value as per `Foreground` above.
 * `"ResetAttributes"` - reset all attributes to default. (*Since: 20220807-113146-c2fee766*)
+
+This example shows how to use arbitrary escape sequences to change the underline color:
+
+```lua
+local wezterm = require 'wezterm'
+wezterm.log_info(wezterm.format {
+  -- turn on underlines
+  { Attribute = { Underline = 'Single' } },
+  -- make the underline red
+  { Text = '\x1b[58:2::255:0:0m' },
+  -- and say hello
+  { Text = 'hello' },
+})
+```