From b2764ad4b11605f91087d95b467451c9bb046b96 Mon Sep 17 00:00:00 2001
From: Fabian Homborg <FHomborg@gmail.com>
Date: Fri, 30 Jul 2021 20:04:38 +0200
Subject: [PATCH] docs

---
 doc_src/cmds/string-length.rst | 24 +++++++++++++++++++++++-
 doc_src/cmds/string-pad.rst    |  6 +++++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/doc_src/cmds/string-length.rst b/doc_src/cmds/string-length.rst
index 1cb84058e..3b609b5f5 100644
--- a/doc_src/cmds/string-length.rst
+++ b/doc_src/cmds/string-length.rst
@@ -1,3 +1,5 @@
+.. _cmd-string-length:
+
 string-length - print string lengths
 ====================================
 
@@ -8,7 +10,7 @@ Synopsis
 
 ::
 
-    string length [(-q | --quiet)] [STRING...]
+    string length [(-q | --quiet)] [(-V | --visible)] [STRING...]
 
 .. END SYNOPSIS
 
@@ -19,6 +21,8 @@ Description
 
 ``string length`` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
 
+With ``-V`` or ``--visible``, it uses the visible width of the arguments. That means it will discount escape sequences fish knows about, account for $fish_emoji_width and $fish_ambiguous_width. It will also count each line (separated by ``\n``) on its own, and with a carriage return (``\r``) count only the widest stretch on a line. The intent is to measure the number of columns the STRING would occupy in the current terminal.
+
 .. END DESCRIPTION
 
 Examples
@@ -36,4 +40,22 @@ Examples
     0
     # Equivalent to test -n "$str"
 
+    >_ string length --visible (set_color red)foobar
+    # the set_color is discounted, so this is the width of "foobar"
+    6
+
+    >_ string length --visible 🐟🐟🐟🐟
+    # depending on $fish_emoji_width, this is either 4 or 8
+    # in new terminals it should be
+    8
+    
+    >_ string length --visible abcdef\r123
+    # this displays as "123def", so the width is 6
+    6
+
+    >_ string length --visible a\nbc
+    # counts "a" and "bc" as separate lines, so it prints width for each
+    1
+    2
+
 .. END EXAMPLES
diff --git a/doc_src/cmds/string-pad.rst b/doc_src/cmds/string-pad.rst
index ee83386ef..6b1a0a5fc 100644
--- a/doc_src/cmds/string-pad.rst
+++ b/doc_src/cmds/string-pad.rst
@@ -17,7 +17,9 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string pad`` extends each STRING to the given width by adding CHAR to the left.
+``string pad`` extends each STRING to the given visible width by adding CHAR to the left. That means the width of all visible characters added together, excluding escape sequences and accounting for $fish_emoji_width and $fish_ambiguous_width. It is the amount of columns in a terminal the STRING occupies.
+
+The escape sequences reflect what *fish* knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about.
 
 If ``-r`` or ``--right`` is given, add the padding after a string.
 
@@ -52,4 +54,6 @@ See Also
 
 - The :ref:`printf <cmd-printf>` command can do simple padding, for example ``printf %10s\n`` works like ``string pad -w10``.
 
+- :ref:`string length <cmd-string-length>` with the ``--visible`` option can be used to show what fish thinks the width is.
+
 .. END EXAMPLES