From e3382b1a62b296c31e6aa84af1ab436791e67675 Mon Sep 17 00:00:00 2001
From: Andrew Wood <ivarch657@gmail.com>
Date: Fri, 13 Dec 2024 23:15:08 +0000
Subject: [PATCH] Document the %{bar-*} format sequences.

---
 docs/pv.1    | 27 +++++++++++++++++++++++++--
 docs/pv.1.md | 28 +++++++++++++++++++++++++++-
 2 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/docs/pv.1 b/docs/pv.1
index cca58d9..4fb26dd 100644
--- a/docs/pv.1
+++ b/docs/pv.1
@@ -1,4 +1,4 @@
-.TH PV 1 2024-12-10 pv-1.9.15 "User Commands"
+.TH PV 1 2024-12-13 pv-1.9.15 "User Commands"
 .\"
 .SH NAME
 pv \- monitor the progress of data through a pipe
@@ -391,7 +391,7 @@ Equivalent to \*(lq\fB\-\-progress\fR\*(rq.
 Expands to fill the remaining space unless prefixed by a number to set the
 width, such as \*(lq\fB%20p\fR\*(rq or \*(lq\fB%20{progress}\fR\*(rq.
 .TP
-.B %{progress-bar-only}
+.BR %{progress-bar-only} ", " %{bar} ", " %{bar-default}
 Progress bar, without any sides, and without any percentage displayed
 afterwards.
 Expands to fill the remaining space unless prefixed by a number.
@@ -400,6 +400,29 @@ Expands to fill the remaining space unless prefixed by a number.
 The percentage completion (or maximum rate, with \*(lq\fB\-\-gauge\fR\*(rq
 when the size is unknown).
 .TP
+.B %{bar-block}
+Progress bar using Unicode full blocks, without any sides, and without any
+percentage displayed afterwards.
+Expands to fill the remaining space unless prefixed by a number.
+If UTF-8 output is not available, the default format is used.
+.TP
+.B %{bar-granular}
+Progress bar using Unicode full blocks, and 1/8th blocks for partial fills,
+providing a more granular display.
+Like the other \*(lq%{bar}\*(rq strings this shows the bar without any
+sides, and without any percentage displayed afterwards, and expands to fill
+the remaining space unless prefixed by a number.
+If UTF-8 output is not available, the default format is used.
+.TP
+.B %{bar-shaded}
+Progress bar using Unicode full blocks and shade characters - dark and
+medium shade are used for partial fills, and the light shade is used for the
+background.
+Like the other \*(lq%{bar}\*(rq strings this shows the bar without any
+sides, and without any percentage displayed afterwards, and expands to fill
+the remaining space unless prefixed by a number.
+If UTF-8 output is not available, the default format is used.
+.TP
 .BR %t ", " %{timer}
 Elapsed time.
 Equivalent to \*(lq\fB\-\-timer\fR\*(rq.
diff --git a/docs/pv.1.md b/docs/pv.1.md
index a9378e6..9d56a71 100644
--- a/docs/pv.1.md
+++ b/docs/pv.1.md
@@ -403,7 +403,7 @@ contain the following sequences:
     unless prefixed by a number to set the width, such as "**%20p**" or
     "**%20{progress}**".
 
-**%{progress-bar-only}**
+**%{progress-bar-only}**, **%{bar}**, **%{bar-default}**
 
 :   Progress bar, without any sides, and without any percentage
     displayed afterwards. Expands to fill the remaining space unless
@@ -414,6 +414,32 @@ contain the following sequences:
 :   The percentage completion (or maximum rate, with "**\--gauge**" when
     the size is unknown).
 
+**%{bar-block}**
+
+:   Progress bar using Unicode full blocks, without any sides, and
+    without any percentage displayed afterwards. Expands to fill the
+    remaining space unless prefixed by a number. If UTF-8 output is not
+    available, the default format is used.
+
+**%{bar-granular}**
+
+:   Progress bar using Unicode full blocks, and 1/8th blocks for partial
+    fills, providing a more granular display. Like the other "%{bar}"
+    strings this shows the bar without any sides, and without any
+    percentage displayed afterwards, and expands to fill the remaining
+    space unless prefixed by a number. If UTF-8 output is not available,
+    the default format is used.
+
+**%{bar-shaded}**
+
+:   Progress bar using Unicode full blocks and shade characters - dark
+    and medium shade are used for partial fills, and the light shade is
+    used for the background. Like the other "%{bar}" strings this shows
+    the bar without any sides, and without any percentage displayed
+    afterwards, and expands to fill the remaining space unless prefixed
+    by a number. If UTF-8 output is not available, the default format is
+    used.
+
 **%t**, **%{timer}**
 
 :   Elapsed time. Equivalent to "**\--timer**".