Document the new "=NAME" (#95) and "@FILE" (#12) syntax for --watchfd options.

docs/pv.1

@@ -7,7 +7,8 @@ pv \- monitor the progress of data through a pipe
 .B pv
 [\fIOPTION\fR]... [\fIFILE\fR]...
 .PP
-\fBpv\fR [\fIOPTION\fR]... \fB\-d\fR|\fB\-\-watchfd\fR \fIPID\fR[:\fIFD\fR]...
+\fBpv\fR [\fIOPTION\fR]... \fB\-d\fR|\fB\-\-watchfd\fR
+\fIPID\fR[:\fIFD\fR]|=\fINAME\fR|@\fILISTFILE\fR...
 .PP
 \fBpv\fR \fB\-R\fR|\fB\-\-remote\fR \fIPID\fR [\fIOPTION\fR]...
 .\"
@@ -349,7 +350,7 @@ doesn't affect the progress display.
 .\"
 .SS "Alternative operating modes"
 .TP
-.BI \-d\  PID\fR[\fB:\fR\fIFD\fR],\  \fB\-\-watchfd\  PID\fR[\fB:\fR\fIFD\fR]
+\fB\-d\fR, \fB\-\-watchfd\fR \fIPID\fR[\fB:\fR\fIFD\fR]|=\fINAME\fR|@\fILISTFILE\fR...
 Instead of transferring data, watch file descriptor \fIFD\fR of process
 \fIPID\fR, and show its progress.
 Other data transfer modifiers - and remote control - may not be used with
@@ -359,8 +360,14 @@ If a \fIPID\fR is specified without an \fIFD\fR, then that process will be
 watched, and all regular files and block devices it opens will be shown with
 a progress bar.
 .IP
-All remaining non-option arguments will also be treated as
-\fIPID\fRs or as \fIPID\fR:\fIFD\fR pairs.
+If a \fINAME\fR is specified, prefixed with "=", then processes with that
+name will be found with \fBpgrep\fR(1), and as watched described above.
+.IP
+If a \fILISTFILE\fR is specified, prefixed with "@", the lines in that file
+will be used as additional arguments.
+.IP
+All remaining non-option arguments will also be treated as additional
+arguments.
 .IP
 The \fBpv\fR process will exit when all \fIFD\fRs have either changed to a
 different file, changed read/write mode, or have closed, and all \fIPID\fRs

docs/pv.1.md

@@ -6,7 +6,8 @@ pv - monitor the progress of data through a pipe
 
 **pv** \[*OPTION*\]\... \[*FILE*\]\...
 
-**pv** \[*OPTION*\]\... **-d**\|**\--watchfd** *PID*\[:*FD*\]\...
+**pv** \[*OPTION*\]\... **-d**\|**\--watchfd**
+*PID*\[:*FD*\]\|=*NAME*\|@*LISTFILE*\...
 
 **pv** **-R**\|**\--remote** *PID* \[*OPTION*\]\...
 
@@ -361,7 +362,7 @@ are explicitly switched on will be shown.
 
 ## Alternative operating modes
 
-**-d PID\[:FD\], \--watchfd PID\[:FD\]**
+**-d**, **\--watchfd** *PID*\[**:***FD*\]\|=*NAME*\|@*LISTFILE*\...
 
 :   Instead of transferring data, watch file descriptor *FD* of process
     *PID*, and show its progress. Other data transfer modifiers - and
@@ -371,8 +372,15 @@ are explicitly switched on will be shown.
     watched, and all regular files and block devices it opens will be
     shown with a progress bar.
 
-    All remaining non-option arguments will also be treated as *PID*s or
-    as *PID*:*FD* pairs.
+    If a *NAME* is specified, prefixed with \"=\", then processes with
+    that name will be found with **pgrep**(1), and as watched described
+    above.
+
+    If a *LISTFILE* is specified, prefixed with \"@\", the lines in that
+    file will be used as additional arguments.
+
+    All remaining non-option arguments will also be treated as
+    additional arguments.
 
     The **pv** process will exit when all *FD*s have either changed to a
     different file, changed read/write mode, or have closed, and all

src/main/options.c

@@ -157,7 +157,6 @@ static bool opts_watchfd_add_item(opts_t opts, pid_t pid, int fd)
  */
 static bool opts_watchfd_processname(opts_t opts, const char *process_name)
 {
-	/* TODO: document "-d =NAME" syntax */
 	/* TODO: read from pgrep, without using popen() or system() */
 	return false;
 }
@@ -173,8 +172,6 @@ static bool opts_watchfd_listfile(opts_t opts, const char *filename)
 	char buffer[1024];		 /* flawfinder: ignore */
 	unsigned int linenumber;
 
-	/* TODO: document "-d @FILE" syntax */
-
 	/*
 	 * flawfinder: buffer is zeroed before each use, and fgets() is
 	 * passed one less than its size so the string functions in the loop