From f7ccb79147556e3b450922cfde8d6059f2e762fb Mon Sep 17 00:00:00 2001 From: Andrew Wood Date: Sat, 2 Sep 2023 00:38:33 +0100 Subject: [PATCH] Corrected manual formatting of arguments - all replaceable items such as arguments should be in italic, as per the conventions described in man(1). --- doc/pv.1 | 82 +++++++++++++++++----------------- doc/pv.1.md | 124 ++++++++++++++++++++++++++++------------------------ 2 files changed, 108 insertions(+), 98 deletions(-) diff --git a/doc/pv.1 b/doc/pv.1 index caeb4b3..97c8e11 100644 --- a/doc/pv.1 +++ b/doc/pv.1 @@ -1,4 +1,4 @@ -.TH PV 1 "August 2023" Linux "User Manuals" +.TH PV 1 "September 2023" Linux "User Manuals" .SH NAME pv \- monitor the progress of data through a pipe .SH SYNOPSIS @@ -22,11 +22,11 @@ standard output and progress will be shown on standard error. .B pv will copy each supplied -.B FILE +.I FILE in turn to standard output .BR "" "(" - means standard input), or if no -.BR FILE s +.IR FILE s are specified just standard input is copied. This is the same behaviour as .BR cat (1). @@ -163,9 +163,9 @@ in the section below. Implies .BR \-C . .TP -.B \-A, \-\-last\-written NUM +.BI \-A\ NUM \fR,\ \fB\-\-last\-written\ NUM Show the last -.B NUM +.I NUM bytes written - but see the caveat under .B %nA in the @@ -173,7 +173,7 @@ in the section below. Implies .BR \-C . .TP -.B \-F, \-\-format FORMAT +.BI \-F\ FORMAT \fR,\ \fB\-\-format\ FORMAT Ignore the options .BR \-p , .BR \-t , @@ -185,7 +185,7 @@ Ignore the options and .BR \-A , and instead use the format string -.B FORMAT +.I FORMAT to determine the output format. See the .B FORMATTING section below. @@ -239,23 +239,23 @@ or .BR mcrypt (1) which require a passphrase before data can be processed. .TP -.B \-D, \-\-delay-start SEC +.BI \-D\ SEC \fR,\ \fB\-\-delay\-start\ SEC Wait until -.B SEC +.I SEC seconds have passed before showing any progress information, for example in a script where you only want to show a progress bar if it starts taking a long time. Note that this can be a decimal such as 0.5. .TP -.B \-s SIZE, \-\-size SIZE +.BI \-s\ SIZE \fR,\ \fB\-\-size\ SIZE Assume the total amount of data to be transferred is -.B SIZE +.I SIZE bytes when calculating percentages and ETAs. The same suffixes of "k", "m" etc can be used as with .BR -L . .TP .B "" If -.B SIZE +.I SIZE starts with .BR "@" , the size of file whose name follows the @@ -266,7 +266,7 @@ will be used. Note that .B \-\-size has no effect if used with -.B -d PID +.BI \-d\ PID to watch all file descriptors of a process, but will work with .BR "-d PID:FD" . .TP @@ -287,35 +287,35 @@ calculated. Count lines as terminated with a zero byte instead of with a newline. This option implies \-\-line\-mode. .TP -.B \-i SEC, \-\-interval SEC +.BI \-i\ SEC \fR,\ \fB\-\-interval\ SEC Wait -.B SEC +.I SEC seconds between updates. The default is to update every second. Note that this can be a decimal such as 0.1. .TP -.B \-m SEC, \-\-average-rate-window SEC +.BI \-m\ SEC \fR,\ \fB\-\-average-rate-window\ SEC Compute current average rate over a -.B SEC -seconds window for average rate and ETA calculations (default 30s). +.I SEC +seconds window for average rate and ETA calculations (default 30 seconds). .TP -.B \-w WIDTH, \-\-width WIDTH +.BI \-w\ WIDTH \fR,\ \fB\-\-width\ WIDTH Assume the terminal is -.B WIDTH +.I WIDTH characters wide, instead of trying to work it out (or assuming 80 if it cannot be guessed). If this option is used, the output width will not be adjusted if the width of the terminal changes while the transfer is running. .TP -.B \-H HEIGHT, \-\-height HEIGHT +.BI \-H\ HEIGHT \fR,\ \fB\-\-height\ HEIGHT Assume the terminal is -.B HEIGHT +.I HEIGHT rows high, instead of trying to work it out (or assuming 25 if it cannot be guessed). If this option is used, the output height will not be adjusted if the height of the terminal changes while the transfer is running. .TP -.B \-N NAME, \-\-name NAME +.BI \-N\ NAME \fR,\ \fB\-\-name\ NAME Prefix the output information with -.BR NAME . +.IR NAME . Useful in conjunction with .B \-c if you have a complicated pipeline and you want to be able to tell different @@ -338,15 +338,15 @@ invocations in a single, long, pipeline. .SH DATA TRANSFER MODIFIERS .TP -.B \-L RATE, \-\-rate-limit RATE +.BI \-L\ RATE \fR,\ \fB\-\-rate-limit\ RATE Limit the transfer to a maximum of -.B RATE +.I RATE bytes per second. A suffix of "K", "M", "G", or "T" can be added to denote kibibytes (*1024), mebibytes, and so on. .TP -.B \-B BYTES, \-\-buffer-size BYTES +.BI \-B\ BYTES \fR,\ \fB\-\-buffer-size\ BYTES Use a transfer buffer size of -.B BYTES +.I BYTES bytes. A suffix of "K", "M", "G", or "T" can be added to denote kibibytes (*1024), mebibytes, and so on. The default buffer size is the block size of the input file's filesystem multiplied by 32 (512KiB max), or @@ -417,7 +417,7 @@ may improve the accuracy of the progress bar when writing to a slow disk. .TP .B \-K, \-\-direct-io Set the -.I O_DIRECT +.B O_DIRECT flag on all inputs and outputs, if it is available. This will minimise the effect of caches, at the cost of performance. Due to memory alignment requirements, it also may cause read or write failures with an error of @@ -435,36 +435,36 @@ except that is never called. Implies .BR \-C . .TP -.B \-d PID[:FD], \-\-watchfd PID[:FD] +.BI \-d\ PID\fR[\fB:\fR\fIFD\fR],\ \fB\-\-watchfd\ PID\fR[\fB:\fR\fIFD\fR] Instead of transferring data, watch file descriptor -.B FD +.I FD of process -.BR PID , +.IR PID , and show its progress. The .B pv process will exit when -.B FD +.I FD either changes to a different file, changes read/write mode, or is closed; other data transfer modifiers - and remote control - may not be used with this option. .TP .B "" If only a -.B PID +.I PID is specified, then that process will be watched, and all regular files and block devices it opens will be shown with a progress bar. The .B pv process will exit when process -.B PID +.I PID exits. .TP -.B \-R PID, \-\-remote PID +.BI \-R\ PID \fR,\ \fB\-\-remote\ PID If -.B PID +.I PID is an instance of .B pv that is already running, -.B \-R PID +.BI \-R\ PID will cause that instance to act as though it had been given this instance's command line instead. For example, if .B pv -L 123K @@ -482,11 +482,11 @@ and .SH GENERAL OPTIONS .TP -.B \-P FILE, \-\-pidfile FILE +.BI \-P\ FILE \fR,\ \fB\-\-pidfile\ FILE Save the process ID of .B pv in -.BR FILE . +.IR FILE . The file will be replaced if it already exists, and will be removed when .B pv exits. While @@ -697,7 +697,7 @@ home page: .BR splice (2), .BR open (2) (for -.IR O_DIRECT ) +.BR O_DIRECT ) .SH LICENSE This is free software, distributed under the ARTISTIC 2.0 license. diff --git a/doc/pv.1.md b/doc/pv.1.md index 2031bcb..132232d 100644 --- a/doc/pv.1.md +++ b/doc/pv.1.md @@ -17,9 +17,9 @@ To use it, insert it in a pipeline between two processes, with the appropriate options. Its standard input will be passed through to its standard output and progress will be shown on standard error. -**pv** will copy each supplied **FILE** in turn to standard output -(**-** means standard input), or if no **FILE**s are specified just -standard input is copied. This is the same behaviour as **cat**(1). +**pv** will copy each supplied *FILE* in turn to standard output (**-** +means standard input), or if no *FILE*s are specified just standard +input is copied. This is the same behaviour as **cat**(1). A simple example to watch how quickly a file is transferred using **nc**(1): @@ -127,15 +127,15 @@ that are explicitly switched on will be shown. percentage of the transfer buffer in use - but see the caveat under **%T** in the **FORMATTING** section below. Implies **-C**. -**-A, \--last-written NUM** +**-A ***NUM***, **\--last-written *****NUM* -: Show the last **NUM** bytes written - but see the caveat under - **%nA** in the **FORMATTING** section below. Implies **-C**. +: Show the last *NUM* bytes written - but see the caveat under **%nA** + in the **FORMATTING** section below. Implies **-C**. -**-F, \--format FORMAT** +**-F ***FORMAT***, **\--format *****FORMAT* : Ignore the options **-p**, **-t**, **-e**, **-r**, **-a**, **-b**, - **-T**, and **-A**, and instead use the format string **FORMAT** to + **-T**, and **-A**, and instead use the format string *FORMAT* to determine the output format. See the **FORMATTING** section below. **-n, \--numeric** @@ -170,24 +170,25 @@ that are explicitly switched on will be shown. starts, eg piping data into **gpg**(1) or **mcrypt**(1) which require a passphrase before data can be processed. -**-D, \--delay-start SEC** +**-D ***SEC***, **\--delay-start *****SEC* -: Wait until **SEC** seconds have passed before showing any progress +: Wait until *SEC* seconds have passed before showing any progress information, for example in a script where you only want to show a progress bar if it starts taking a long time. Note that this can be a decimal such as 0.5. -**-s SIZE, \--size SIZE** +**-s ***SIZE***, **\--size *****SIZE* -: Assume the total amount of data to be transferred is **SIZE** bytes +: Assume the total amount of data to be transferred is *SIZE* bytes when calculating percentages and ETAs. The same suffixes of \"k\", \"m\" etc can be used as with **-L**. -: If **SIZE** starts with **@**, the size of file whose name follows - the **@** will be used. +: If *SIZE* starts with **@**, the size of file whose name follows the + **@** will be used. -: Note that **\--size** has no effect if used with **-d PID** to watch - all file descriptors of a process, but will work with **-d PID:FD**. +: Note that **\--size** has no effect if used with **-d ***PID* to + watch all file descriptors of a process, but will work with **-d + PID:FD**. **-l, \--line-mode** @@ -205,29 +206,33 @@ are unreadable, the total size will not be calculated. : Count lines as terminated with a zero byte instead of with a newline. This option implies \--line-mode. -**-i SEC, \--interval SEC** +**-i ***SEC***, **\--interval *****SEC* -: Wait **SEC** seconds between updates. The default is to update every +: Wait *SEC* seconds between updates. The default is to update every second. Note that this can be a decimal such as 0.1. -**-m SEC, \--average-rate-window SEC** +**-m ***SEC***, **\--average-rate-window *****SEC* -: Compute current average rate over a **SEC** seconds window for - average rate and ETA calculations (default 30s). +: Compute current average rate over a *SEC* seconds window for average + rate and ETA calculations (default 30 seconds). -**-w WIDTH, \--width WIDTH** +**-w ***WIDTH***, **\--width *****WIDTH* -: Assume the terminal is **WIDTH** characters wide, instead of trying - to work it out (or assuming 80 if it cannot be guessed). +: Assume the terminal is *WIDTH* characters wide, instead of trying to + work it out (or assuming 80 if it cannot be guessed). If this option + is used, the output width will not be adjusted if the width of the + terminal changes while the transfer is running. -**-H HEIGHT, \--height HEIGHT** +**-H ***HEIGHT***, **\--height *****HEIGHT* -: Assume the terminal is **HEIGHT** rows high, instead of trying to - work it out (or assuming 25 if it cannot be guessed). +: Assume the terminal is *HEIGHT* rows high, instead of trying to work + it out (or assuming 25 if it cannot be guessed). If this option is + used, the output height will not be adjusted if the height of the + terminal changes while the transfer is running. -**-N NAME, \--name NAME** +**-N ***NAME***, **\--name *****NAME* -: Prefix the output information with **NAME**. Useful in conjunction +: Prefix the output information with *NAME*. Useful in conjunction with **-c** if you have a complicated pipeline and you want to be able to tell different parts of it apart. @@ -245,15 +250,15 @@ are unreadable, the total size will not be calculated. # DATA TRANSFER MODIFIERS -**-L RATE, \--rate-limit RATE** +**-L ***RATE***, **\--rate-limit *****RATE* -: Limit the transfer to a maximum of **RATE** bytes per second. A - suffix of \"K\", \"M\", \"G\", or \"T\" can be added to denote - kibibytes (\*1024), mebibytes, and so on. +: Limit the transfer to a maximum of *RATE* bytes per second. A suffix + of \"K\", \"M\", \"G\", or \"T\" can be added to denote kibibytes + (\*1024), mebibytes, and so on. -**-B BYTES, \--buffer-size BYTES** +**-B ***BYTES***, **\--buffer-size *****BYTES* -: Use a transfer buffer size of **BYTES** bytes. A suffix of \"K\", +: Use a transfer buffer size of *BYTES* bytes. A suffix of \"K\", \"M\", \"G\", or \"T\" can be added to denote kibibytes (\*1024), mebibytes, and so on. The default buffer size is the block size of the input file\'s filesystem multiplied by 32 (512KiB max), or @@ -267,11 +272,11 @@ are unreadable, the total size will not be calculated. **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 - **-A** and **-T** from working, and makes **-B** redundant, so using - **-A**, **-T**, or **-B** automatically switches on **-C**. - Switching on **-C** results in a small loss of transfer efficiency. - (This option has no effect on systems where **splice**(2) is - unavailable). + **-A** and **-T** from working, cannot work with **-X**, and makes + **-B** redundant, so using **-A**, **-T**, **-X**, or **-B** + automatically switches on **-C**. Switching on **-C** results in a + small loss of transfer efficiency. (This option has no effect on + systems where **splice**(2) is unavailable). **-E, \--skip-errors** @@ -300,30 +305,35 @@ are unreadable, the total size will not be calculated. **-K, \--direct-io** -: Set the *O_DIRECT* flag on all inputs and outputs, if it is +: Set the **O_DIRECT** flag on all inputs and outputs, if it is available. This will minimise the effect of caches, at the cost of performance. Due to memory alignment requirements, it also may cause read or write failures with an error of \"Invalid argument\", especially if reading and writing files across a variety of filesystems in a single **pv** call. Use this option with caution. -**-d PID\[:FD\], \--watchfd PID\[:FD\]** +**-X, \--discard** -: Instead of transferring data, watch file descriptor **FD** of - process **PID**, and show its progress. The **pv** process will exit - when **FD** either changes to a different file, changes read/write - mode, or is closed; other data transfer modifiers - and remote - control - may not be used with this option. +: Instead of transferring input data to standard output, discard it. + This is equivalent to redirecting standard output to */dev/null*, + except that **write**(2) is never called. Implies **-C**. -: If only a **PID** is specified, then that process will be watched, - and all regular files and block devices it opens will be shown with - a progress bar. The **pv** process will exit when process **PID** - exits. +**-d ***PID\[**:***FD*\], *****\--watchfd *****PID\[**:***FD*\]* -**-R PID, \--remote PID** +: Instead of transferring data, watch file descriptor *FD* of process + *PID*, and show its progress. The **pv** process will exit when *FD* + either changes to a different file, changes read/write mode, or is + closed; other data transfer modifiers - and remote control - may not + be used with this option. -: If **PID** is an instance of **pv** that is already running, **-R - PID** will cause that instance to act as though it had been given +: If only a *PID* is specified, then that process will be watched, and + all regular files and block devices it opens will be shown with a + progress bar. The **pv** process will exit when process *PID* exits. + +**-R ***PID***, **\--remote *****PID* + +: If *PID* is an instance of **pv** that is already running, **-R + ***PID* will cause that instance to act as though it had been given this instance\'s command line instead. For example, if **pv -L 123K** is running with process ID 9876, then running **pv -R 9876 -L 321K** will cause it to start using a rate limit of 321KiB instead @@ -332,9 +342,9 @@ are unreadable, the total size will not be calculated. # GENERAL OPTIONS -**-P FILE, \--pidfile FILE** +**-P ***FILE***, **\--pidfile *****FILE* -: Save the process ID of **pv** in **FILE**. The file will be replaced +: Save the process ID of **pv** in *FILE*. The file will be replaced if it already exists, and will be removed when **pv** exits. While **pv** is running, it will contain a single number - the process ID of **pv** - followed by a newline. @@ -520,7 +530,7 @@ from the **pv** home page: \ # SEE ALSO -**cat**(1), **dialog**(1), **splice**(2), **open**(2) (for *O_DIRECT*) +**cat**(1), **dialog**(1), **splice**(2), **open**(2) (for **O_DIRECT**) # LICENSE