From 94f4a239ccb5cce1adbdcfc769bd6f51c781deb0 Mon Sep 17 00:00:00 2001
From: Andrew Wood <ivarch657@gmail.com>
Date: Mon, 14 Oct 2024 21:46:01 +0100
Subject: [PATCH] Document the zsh 5.8 issue from #105 in the manual.

---
 docs/pv.1    | 36 ++++++++++++++++++++++++++++++++++++
 docs/pv.1.md | 15 +++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/docs/pv.1 b/docs/pv.1
index 5882b8b..18f245f 100644
--- a/docs/pv.1
+++ b/docs/pv.1
@@ -779,6 +779,42 @@ one that owns the terminal.  In these cases, use
 .BR \-\-force .
 .P
 .IP \(bu 3
+If
+.B pv
+is used in a pipeline in
+.B zsh
+version 5.8, and the last command in the pipeline is based on shell
+builtins,
+.B zsh
+takes control of the terminal away from
+.BR pv ,
+preventing progress from being displayed.  For example, this will produce no
+progress bar:
+
+.in +4n
+.EX
+pv InputFile | { while read -r line; do sleep 0.001; done; }
+.EE
+.in
+.PP
+.IP "" 3
+To work around this, put the last commands of the pipeline in
+normal brackets to force the use of a subshell:
+
+.in +4n
+.EX
+pv InputFile | ( while read -r line; do sleep 0.001; done; )
+.EE
+.in
+.PP
+.IP "" 3
+Refer to
+.UR https://codeberg.org/a-j-wood/pv/issues/105
+issue #105
+.UE
+for full details.
+.P
+.IP \(bu 3
 The
 .B -c
 option does not work properly on Cygwin without
diff --git a/docs/pv.1.md b/docs/pv.1.md
index 53a519c..14914fc 100644
--- a/docs/pv.1.md
+++ b/docs/pv.1.md
@@ -589,6 +589,21 @@ The following problems are known to exist in **pv**:
     in a separate process group from the one that owns the terminal. In
     these cases, use **\--force**.
 
+-   If **pv** is used in a pipeline in **zsh** version 5.8, and the last
+    command in the pipeline is based on shell builtins, **zsh** takes
+    control of the terminal away from **pv**, preventing progress from
+    being displayed. For example, this will produce no progress bar:
+
+    pv InputFile | { while read -r line; do sleep 0.001; done; }
+
+:   To work around this, put the last commands of the pipeline in normal
+    brackets to force the use of a subshell:
+
+    pv InputFile | ( while read -r line; do sleep 0.001; done; )
+
+:   Refer to [issue #105](https://codeberg.org/a-j-wood/pv/issues/105)
+    for full details.
+
 -   The **-c** option does not work properly on Cygwin without
     **cygserver** running, if started near the bottom of the screen (IPC
     is needed to handle the terminal scrolling). To fix this, start