[PATCH 3/7 V2] lsfd: improve grammar, and use angular brackets around placeholder word

[Benno Schulenberg <bensberg@telfort.nl>]

Also, use <list> (the standard way to indicate multiple arguments) as
argument of --pid,  and don't use "<when>" when the possible arguments
differ from "always", "never", "auto".

In addition, improve some wording and markup in the man page.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>
---
 lsfd-cmd/lsfd.1.adoc | 33 ++++++++++++++++-----------------
 lsfd-cmd/lsfd.c      |  6 +++---
 2 files changed, 19 insertions(+), 20 deletions(-)

diff --git a/lsfd-cmd/lsfd.1.adoc b/lsfd-cmd/lsfd.1.adoc
index b0ba2ba53..2654e8eaf 100644
--- a/lsfd-cmd/lsfd.1.adoc
+++ b/lsfd-cmd/lsfd.1.adoc
@@ -60,22 +60,22 @@ Use raw output format.
 *--notruncate*::
 Don't truncate text in columns.
 
-*-p*, *--pid* _pids_::
-Collect information only for specified processes.
-_pids_ is a list of pids. A comma or whitespaces can be used as separators.
-You can use this option with *pidof*(1). See *FILTER EXAMPLES*.
-+
-Both *-Q* option with an expression including PID, e.g. -Q (PID == 1),
-and *-p* option, e.g. -p 1, may print the same output but using *-p*
-option is much more efficient because *-p* option works at a much earlier
-stage of processing than the *-Q* option.
+*-p*, *--pid* _list_::
+Collect information only for the specified processes.
+The _list_ is a comma-separated list of PIDs.
+See also *FILTER EXAMPLES*.
 
-*-i*[4|6], *--inet*[=4|=6]::
+*-i*[*4*|*6*], *--inet*[**=4**|**=6**]::
 List only IPv4 sockets and/or IPv6 sockets.
 
-*-Q*, *--filter* _expr_::
-Print only the files matching the condition represented by the _expr_.
+*-Q*, *--filter* _expression_::
+Print only the files matching the condition represented by the _expression_.
 See also *scols-filter*(5) and *FILTER EXAMPLES*.
++
+The *-Q* option with a PID (for example: *-Q PID==1*) and the *-p*
+option (for example: *-p 1*) can be used to achieve the same result,
+but using the *-p* option is much more efficient because it works at
+a much earlier stage of processing than the *-Q* option.
 
 *-C*, *--counter* __label__:__filter_expr__::
 Define a custom counter used in *--summary* output. *lsfd* makes a
@@ -85,14 +85,13 @@ counter named _label_. *lsfd* applies filters defined with *--filter*
 options before counting; files excluded by the filters are not counted.
 +
 See *scols-filter*(5) about _filter_expr_.
-_label_ should not include `{` nor `:`. You can define multiple
+_label_ should not include *{* nor *:*. You can define multiple
 counters by specifying this option multiple times.
-+
 See also *COUNTER EXAMPLES*.
 
-*--summary*[**=**__when__]::
-This option controls summary lines output. The optional argument _when_
-can be *only*, *append* or *never*. If the _when_ argument is omitted,
+*--summary*[**=**_mode_]::
+This option controls summary lines output. The optional argument _mode_
+can be *only*, *append*, or *never*. If the _mode_ argument is omitted,
 it defaults to *only*.
 +
 The summary reports counters. A counter consists of a label and an
diff --git a/lsfd-cmd/lsfd.c b/lsfd-cmd/lsfd.c
index 2eb53935c..9e9cb52ac 100644
--- a/lsfd-cmd/lsfd.c
+++ b/lsfd-cmd/lsfd.c
@@ -2190,14 +2190,14 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -o, --output <list>          output columns (see --list-columns)\n"), out);
 	fputs(_(" -r, --raw                    use raw output format\n"), out);
 	fputs(_(" -u, --notruncate             don't truncate text in columns\n"), out);
-	fputs(_(" -p, --pid  <pid(s)>          collect information only specified processes\n"), out);
+	fputs(_(" -p, --pid <list>             collect information only for specified processes\n"), out);
 	fputs(_(" -i[4|6], --inet[=4|=6]       list only IPv4 and/or IPv6 sockets\n"), out);
 	fputs(_(" -Q, --filter <expr>          apply display filter\n"), out);
 	fputs(_("     --debug-filter           dump the internal data structure of filter and exit\n"), out);
 	fputs(_(" -C, --counter <name>:<expr>  define custom counter for --summary output\n"), out);
 	fputs(_("     --dump-counters          dump counter definitions\n"), out);
-	fputs(_("     --hyperlink[=mode]       print paths as terminal hyperlinks (always, never, or auto)\n"), out);
-	fputs(_("     --summary[=<when>]       print summary information (only, append, or never)\n"), out);
+	fputs(_("     --hyperlink[=<when>]     print paths as terminal hyperlinks (always|never|auto)\n"), out);
+	fputs(_("     --summary[=<mode>]       print summary information (append|only|never)\n"), out);
 	fputs(_("     --_drop-privilege        (testing purpose) do setuid(1) just after starting\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
-- 
2.48.1