Document the use of "--numeric" with "--format".

docs/NEWS.md

@@ -1,5 +1,6 @@
-### UNRELEASED
+### 1.9.31 - UNRELEASED
 
+ * *feature:* the **--format** option can now be used with **--numeric** for customised numeric output, such as JSON ([#127](https://codeberg.org/a-j-wood/pv/issues/127))
  * *i18n:* German translations updated
  * *i18n:* Polish translations updated
  * *i18n:* Russian translations updated

docs/pv.1

@@ -1,4 +1,4 @@
-.TH PV 1 2025-01-12 pv-1.9.27 "User Commands"
+.TH PV 1 2025-01-25 pv-1.9.31 "User Commands"
 .\"
 .SH NAME
 pv \- monitor the progress of data through a pipe
@@ -110,6 +110,14 @@ byte/line count).
 Adding \*(lq\fB\-\-timer\fR\*(rq prefixes each output line with the elapsed
 time so far, as a decimal number of seconds.
 .TP
+.B ""
+Combining \*(lq\fB\-\-numeric\fR\*(rq with \*(lq\fB\-\-format\fR\*(rq allows
+for custom output.  The default format string components for
+\*(lq\fB\-\-numeric\fR\*(rq are
+\*(lq\fB%t\~%b\~%r\~%{progress\-amount\-only}\fR\*(rq in that order, each
+item being active or inactive according to the rules above (so the default
+with no other options is \*(lq\fB%{progress\-amount\-only}\fR\*(rq.
+.TP
 .B \-q, \-\-quiet
 No output.
 Useful if the \*(lq\fB\-\-rate\-limit\fR\*(rq option is being used on its
@@ -666,6 +674,14 @@ the progress display:
 pv \-\-format '%a %p : %L' big.log | processing-script
 .EE
 .in
+.PP
+Showing progress as lines of JSON data:
+.PP
+.in +4
+.EX
+pv \-\-numeric \-\-format '{"elapsed":%t,"bytes":%b,"rate":%r,"percentage":%{progress-amount-only}}' big.log | processing-script
+.EE
+.in
 .\"
 .SH EXIT STATUS
 An exit status of 1 indicates a problem with the \*(lq\fB\-\-remote\fR\*(rq

docs/pv.1.md

@@ -109,6 +109,12 @@ are explicitly switched on will be shown.
     count). Adding "**\--timer**" prefixes each output line with the
     elapsed time so far, as a decimal number of seconds.
 
+:   Combining "**\--numeric**" with "**\--format**" allows for custom
+    output. The default format string components for "**\--numeric**"
+    are "**%t %b %r %{progress-amount-only}**" in that order, each item
+    being active or inactive according to the rules above (so the
+    default with no other options is "**%{progress-amount-only}**".
+
 **-q, \--quiet**
 
 :   No output. Useful if the "**\--rate-limit**" option is being used on
@@ -629,6 +635,10 @@ part of the progress display:
 
     pv --format '%a %p : %L' big.log | processing-script
 
+Showing progress as lines of JSON data:
+
+    pv --numeric --format '{"elapsed":%t,"bytes":%b,"rate":%r,"percentage":%{progress-amount-only}}' big.log | processing-script
+
 # EXIT STATUS
 
 An exit status of 1 indicates a problem with the "**\--remote**" or