From 7e99aa5b13a95223240fc598b2fbec226010c29f Mon Sep 17 00:00:00 2001
From: Andrew Wood <andrew.wood@ivarch.com>
Date: Fri, 22 May 2026 21:43:30 +0100
Subject: [PATCH] Expand the description of --no-splice.

---
 docs/pv.1    | 24 +++++++++++++++---------
 docs/pv.1.md | 24 +++++++++++++++---------
 2 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/docs/pv.1 b/docs/pv.1
index 6b32cdb..662997c 100644
--- a/docs/pv.1
+++ b/docs/pv.1
@@ -290,16 +290,22 @@ better with specific buffer sizes such as 1024.
 Implies \*(lq\fB\-\-no\-splice\fR\*(rq.
 .TP
 .B \-C, \-\-no-splice
-Never use \fBsplice\fR(2), even if it would normally be possible.
-The \fBsplice\fR(2) system call is a more efficient way of transferring data
-from or to a pipe than regular \fBread\fR(2) and \fBwrite\fR(2), but means
-that the transfer buffer may not be used.
-This prevents \*(lq\fB\-\-buffer\-percent\fR\*(rq and
-\*(lq\fB\-\-last\-written\fR\*(rq from working, cannot work with
-\*(lq\fB\-\-sparse\fR\*(rq, and makes \*(lq\fB\-\-buffer\-size\fR\*(rq
-redundant, so using any of those options automatically switches on
+Prevent the use of \fBsplice\fR(2), a system call normally used on systems
+that support it to improve efficiency by eliminating the need for a transfer
+buffer.
+.IP
+In the default case that \fBsplice\fR(2) is used, the lack of a transfer
+buffer prevents \*(lq\fB\-\-buffer\-percent\fR\*(rq and
+\*(lq\fB\-\-last\-written\fR\*(rq from working and makes
+\*(lq\fB\-\-buffer\-size\fR\*(rq redundant, so using any of those options
+automatically switches on \*(lq\fB\-\-no\-splice\fR\*(rq.
+.IP
+Sparse files cannot be written with \fBsplice\fR(2), so using
+\*(lq\fB\-\-sparse\fR\*(rq automatically switches on
 \*(lq\fB\-\-no\-splice\fR\*(rq.
-Switching on this option results in a small loss of transfer efficiency.
+.IP
+Switching on \*(lq\fB\-\-no\-splice\fR\*(rq results in a small loss of
+transfer efficiency.
 It has no effect on systems where \fBsplice\fR(2) is unavailable.
 .TP
 .BI \-J\  BYTES \fR,\ \fB\-\-pipe\-buffer\-size\  BYTES
diff --git a/docs/pv.1.md b/docs/pv.1.md
index 534b54e..ad20a9f 100644
--- a/docs/pv.1.md
+++ b/docs/pv.1.md
@@ -297,16 +297,22 @@ are explicitly switched on will be shown.
 
 **-C, \--no-splice**
 
-:   Never use **splice**(2), even if it would normally be possible. The
-    **splice**(2) system call is a more efficient way of transferring
-    data from or to a pipe than regular **read**(2) and **write**(2),
-    but means that the transfer buffer may not be used. This prevents
-    "**\--buffer-percent**" and "**\--last-written**" from working,
-    cannot work with "**\--sparse**", and makes "**\--buffer-size**"
+:   Prevent the use of **splice**(2), a system call normally used on
+    systems that support it to improve efficiency by eliminating the
+    need for a transfer buffer.
+
+    In the default case that **splice**(2) is used, the lack of a
+    transfer buffer prevents "**\--buffer-percent**" and
+    "**\--last-written**" from working and makes "**\--buffer-size**"
     redundant, so using any of those options automatically switches on
-    "**\--no-splice**". Switching on this option results in a small loss
-    of transfer efficiency. It has no effect on systems where
-    **splice**(2) is unavailable.
+    "**\--no-splice**".
+
+    Sparse files cannot be written with **splice**(2), so using
+    "**\--sparse**" automatically switches on "**\--no-splice**".
+
+    Switching on "**\--no-splice**" results in a small loss of transfer
+    efficiency. It has no effect on systems where **splice**(2) is
+    unavailable.
 
 **-J BYTES, \--pipe-buffer-size BYTES**