From 3910291d4d2144f36287d65974ab0fd0a06cbef7 Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@wezfurlong.org>
Date: Wed, 5 Apr 2023 08:18:50 -0700
Subject: [PATCH] docs: update format-tab-title examples

nudge folks towards making their custom formatting aware of the
new tab title stuff
---
 .../lua/window-events/format-tab-title.md     | 44 ++++++++++++++++---
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/docs/config/lua/window-events/format-tab-title.md b/docs/config/lua/window-events/format-tab-title.md
index b9cd3399d..44ab17b27 100644
--- a/docs/config/lua/window-events/format-tab-title.md
+++ b/docs/config/lua/window-events/format-tab-title.md
@@ -21,16 +21,32 @@ but it demonstrates that it is possible to format more than just the text
 shown in the tab.
 
 ```lua
+-- This function returns the suggested title for a tab.
+-- It prefers the title that was set via `tab:set_title()`
+-- or `wezterm cli set-tab-title`, but falls back to the
+-- title of the active pane in that tab.
+function tab_title(tab_info) 
+    local title = tab_info.tab_title
+    -- if the tab title is explicitly set, take that
+    if title and #title > 0 then
+        return title
+    end
+    -- Otherwise, use the title from the active pane
+    -- in that tab
+    return tab.active_pane.title
+end
+
 wezterm.on(
   'format-tab-title',
   function(tab, tabs, panes, config, hover, max_width)
+    local title = tab_title(tab)
     if tab.is_active then
       return {
         { Background = { Color = 'blue' } },
-        { Text = ' ' .. tab.active_pane.title .. ' ' },
+        { Text = ' ' .. title .. ' ' },
       }
     end
-    return tab.active_pane.title
+    return title
   end
 )
 ```
@@ -70,10 +86,26 @@ A more elaborate example:
 local wezterm = require 'wezterm'
 
 -- The filled in variant of the < symbol
-local SOLID_LEFT_ARROW = utf8.char(0xe0b2)
+local SOLID_LEFT_ARROW = wezterm.nerdfonts.pl_right_hard_divider
 
 -- The filled in variant of the > symbol
-local SOLID_RIGHT_ARROW = utf8.char(0xe0b0)
+local SOLID_RIGHT_ARROW = wezterm.nerdfonts.pl_left_hard_divider
+
+-- This function returns the suggested title for a tab.
+-- It prefers the title that was set via `tab:set_title()`
+-- or `wezterm cli set-tab-title`, but falls back to the
+-- title of the active pane in that tab.
+function tab_title(tab_info) 
+    local title = tab_info.tab_title
+    -- if the tab title is explicitly set, take that
+    if title and #title > 0 then
+        return title
+    end
+    -- Otherwise, use the title from the active pane
+    -- in that tab
+    return tab.active_pane.title
+end
+
 
 wezterm.on(
   'format-tab-title',
@@ -92,9 +124,11 @@ wezterm.on(
 
     local edge_foreground = background
 
+    local title = tab_title(tab)
+
     -- ensure that the titles fit in the available space,
     -- and that we have room for the edges.
-    local title = wezterm.truncate_right(tab.active_pane.title, max_width - 2)
+    title = wezterm.truncate_right(title, max_width - 2)
 
     return {
       { Background = { Color = edge_background } },