[iproute PATCH 00/10] Review help texts and man pages

[iproute PATCH 00/10] Review help texts and man pages

[Phil Sutter]

This series fixes a number of issues identified by an automated scan
over man pages and help texts.

Phil Sutter (10):
  man: bridge.8: Document -oneline option
  bridge: trivial: Make help text consistent
  devlink: trivial: Make help text consistent
  man: devlink.8: Document -verbose option
  genl: Fix help text
  man: ifstat.8: Document --json and --pretty options
  ip: Add missing -M flag to help text
  man: rtacct.8: Fix nstat options
  rtmon: List options in help text
  man: ss.8: Describe --events option

 bridge/bridge.c    |  2 +-
 devlink/devlink.c  |  2 +-
 genl/genl.c        |  4 ++--
 ip/ip.c            |  2 +-
 ip/rtmon.c         |  4 +++-
 man/man8/bridge.8  | 15 ++++++++++++++-
 man/man8/devlink.8 |  4 ++++
 man/man8/ifstat.8  |  8 ++++++++
 man/man8/rtacct.8  | 14 +++++++++-----
 man/man8/ss.8      |  3 +++
 10 files changed, 46 insertions(+), 12 deletions(-)

-- 
2.18.0

[iproute PATCH 01/10] man: bridge.8: Document -oneline option

[Phil Sutter]

Copied the description from ip.8.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/bridge.8 | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index 6dfd4178a19cc..53cd3d0a3d933 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -24,7 +24,8 @@ bridge \- show / manipulate bridge addresses and devices
 \fB\-b\fR[\fIatch\fR] filename |
 \fB\-c\fR[\folor\fR] |
 \fB\-p\fR[\fIretty\fR] |
-\fB\-j\fR[\fIson\fR] }
+\fB\-j\fR[\fIson\fR] |
+\fB\-o\fR[\fIneline\fr] }
 
 .ti -8
 .BR "bridge link set"
@@ -191,6 +192,18 @@ Output results in JavaScript Object Notation (JSON).
 .BR "\-p", " \-pretty"
 When combined with -j generate a pretty JSON output.
 
+.TP
+.BR "\-o", " \-oneline"
+output each record on a single line, replacing line feeds
+with the
+.B '\e'
+character. This is convenient when you want to count records
+with
+.BR wc (1)
+or to
+.BR grep (1)
+the output.
+
 
 .SH BRIDGE - COMMAND SYNTAX
 
-- 
2.18.0

[iproute PATCH 02/10] bridge: trivial: Make help text consistent

[Phil Sutter]

Change curly braces into brackets for -json option in help text to be
consistent with the rest.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 bridge/bridge.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bridge/bridge.c b/bridge/bridge.c
index e35e5bdf7fb30..04d84163e68c4 100644
--- a/bridge/bridge.c
+++ b/bridge/bridge.c
@@ -42,7 +42,7 @@ static void usage(void)
 "where	OBJECT := { link | fdb | mdb | vlan | monitor }\n"
 "	OPTIONS := { -V[ersion] | -s[tatistics] | -d[etails] |\n"
 "		     -o[neline] | -t[imestamp] | -n[etns] name |\n"
-"		     -c[ompressvlans] -color -p[retty] -j{son} }\n");
+"		     -c[ompressvlans] -color -p[retty] -j[son] }\n");
 	exit(-1);
 }
 
-- 
2.18.0

[iproute PATCH 03/10] devlink: trivial: Make help text consistent

[Phil Sutter]

Typically the part of the flag in brackets completes the leading part
instead of repeating it.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 devlink/devlink.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/devlink/devlink.c b/devlink/devlink.c
index 784bb84bf7ad6..519ee2577cc4c 100644
--- a/devlink/devlink.c
+++ b/devlink/devlink.c
@@ -5426,7 +5426,7 @@ static void help(void)
 	pr_err("Usage: devlink [ OPTIONS ] OBJECT { COMMAND | help }\n"
 	       "       devlink [ -f[orce] ] -b[atch] filename\n"
 	       "where  OBJECT := { dev | port | sb | monitor | dpipe | resource | region }\n"
-	       "       OPTIONS := { -V[ersion] | -n[no-nice-names] | -j[json] | -p[pretty] | -v[verbose] }\n");
+	       "       OPTIONS := { -V[ersion] | -n[o-nice-names] | -j[son] | -p[retty] | -v[erbose] }\n");
 }
 
 static int dl_cmd(struct dl *dl, int argc, char **argv)
-- 
2.18.0

[iproute PATCH 04/10] man: devlink.8: Document -verbose option

[Phil Sutter]

This was the only bit missing in comparison to devlink help text.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/devlink.8 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/man/man8/devlink.8 b/man/man8/devlink.8
index ac61b6add7fba..360031f77c165 100644
--- a/man/man8/devlink.8
+++ b/man/man8/devlink.8
@@ -47,6 +47,10 @@ Generate JSON output.
 .BR "\-p" , " --pretty"
 When combined with -j generate a pretty JSON output.
 
+.TP
+.BR "\-v" , " --verbose"
+Turn on verbose output.
+
 .SS
 .I OBJECT
 
-- 
2.18.0

[iproute PATCH 05/10] genl: Fix help text

[Phil Sutter]

The '| help' part was misleading: In fact, 'genl help' does not work but
'genl <OBJECT> help' does. Fix the help text to make that clear.

In addition to that, list -Version and -help flags as well.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 genl/genl.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/genl/genl.c b/genl/genl.c
index 20ecb8b63ef62..1940a23c5a99c 100644
--- a/genl/genl.c
+++ b/genl/genl.c
@@ -98,9 +98,9 @@ static void usage(void) __attribute__((noreturn));
 
 static void usage(void)
 {
-	fprintf(stderr, "Usage: genl [ OPTIONS ] OBJECT | help }\n"
+	fprintf(stderr, "Usage: genl [ OPTIONS ] OBJECT [help] }\n"
 	                "where  OBJECT := { ctrl etc }\n"
-	                "       OPTIONS := { -s[tatistics] | -d[etails] | -r[aw] }\n");
+	                "       OPTIONS := { -s[tatistics] | -d[etails] | -r[aw] | -V[ersion] | -h[elp] }\n");
 	exit(-1);
 }
 
-- 
2.18.0

[iproute PATCH 06/10] man: ifstat.8: Document --json and --pretty options

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/ifstat.8 | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/man/man8/ifstat.8 b/man/man8/ifstat.8
index 3ba0088d8940a..8cd164dda6d72 100644
--- a/man/man8/ifstat.8
+++ b/man/man8/ifstat.8
@@ -48,6 +48,14 @@ Report average over the last SECS seconds.
 .B \-z, \-\-zeros
 Show entries with zero activity.
 .TP
+.B \-j, \-\-json
+Display results in JSON format
+.TP
+.B \-p, \-\-pretty
+If combined with
+.BR \-\-json ,
+pretty print the output.
+.TP
 .B \-x, \-\-extended=TYPE
 Show extended stats of TYPE. Supported types are:
 
-- 
2.18.0

[iproute PATCH 07/10] ip: Add missing -M flag to help text

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 ip/ip.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ip/ip.c b/ip/ip.c
index 893c3c43ef99a..93382d671f467 100644
--- a/ip/ip.c
+++ b/ip/ip.c
@@ -55,7 +55,7 @@ static void usage(void)
 "       OPTIONS := { -V[ersion] | -s[tatistics] | -d[etails] | -r[esolve] |\n"
 "                    -h[uman-readable] | -iec | -j[son] | -p[retty] |\n"
 "                    -f[amily] { inet | inet6 | ipx | dnet | mpls | bridge | link } |\n"
-"                    -4 | -6 | -I | -D | -B | -0 |\n"
+"                    -4 | -6 | -I | -D | -M | -B | -0 |\n"
 "                    -l[oops] { maximum-addr-flush-attempts } | -br[ief] |\n"
 "                    -o[neline] | -t[imestamp] | -ts[hort] | -b[atch] [filename] |\n"
 "                    -rc[vbuf] [size] | -n[etns] name | -a[ll] | -c[olor]}\n");
-- 
2.18.0

[iproute PATCH 08/10] man: rtacct.8: Fix nstat options

[Phil Sutter]

Add missing --pretty and --json options, correct --zero to --zeros and
correct the mess around --scan/--interval including broken man page
formatting.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/rtacct.8 | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/man/man8/rtacct.8 b/man/man8/rtacct.8
index 01321e6dbdd60..ccdbf6ca75e57 100644
--- a/man/man8/rtacct.8
+++ b/man/man8/rtacct.8
@@ -4,7 +4,7 @@
 nstat, rtacct - network statistics tools.
 
 .SH SYNOPSIS
-Usage: nstat [ -h?vVzrnasd:t: ] [ PATTERN [ PATTERN ] ]
+Usage: nstat [ -h?vVzrnasd:t:jp ] [ PATTERN [ PATTERN ] ]
 .br
 Usage: rtacct [ -h?vVzrnasd:t: ] [ ListOfRealms ]
 
@@ -21,7 +21,7 @@ Print help
 .B \-V, \-\-version
 Print version
 .TP
-.B \-z, \-\-zero
+.B \-z, \-\-zeros
 Dump zero counters too. By default they are not shown.
 .TP
 .B \-r, \-\-reset
@@ -39,12 +39,16 @@ Do not update history, so that the next time you will see counters including val
 .B \-j, \-\-json
 Display results in JSON format.
 .TP
-.B \-d, \-\-interval <INTERVAL>
+.B \-p, \-\-pretty
+When combined with
+.BR \-\-json ,
+pretty print the output.
+.TP
+.B \-d, \-\-scan <INTERVAL>
 Run in daemon mode collecting statistics. <INTERVAL> is interval between measurements in seconds.
 .TP
-
+.B \-t, \-\-interval <INTERVAL>
 Time interval to average rates. Default value is 60 seconds.
-.TP
 
 .SH SEE ALSO
 lnstat(8)
-- 
2.18.0

[iproute PATCH 09/10] rtmon: List options in help text

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 ip/rtmon.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/ip/rtmon.c b/ip/rtmon.c
index acc11df49b423..0e795f740e627 100644
--- a/ip/rtmon.c
+++ b/ip/rtmon.c
@@ -63,7 +63,9 @@ static int dump_msg2(const struct sockaddr_nl *who,
 
 static void usage(void)
 {
-	fprintf(stderr, "Usage: rtmon file FILE [ all | LISTofOBJECTS]\n");
+	fprintf(stderr, "Usage: rtmon [ OPTIONS ] file FILE [ all | LISTofOBJECTS ]\n");
+	fprintf(stderr, "OPTIONS := { -f[amily] { inet | inet6 | link | help } |\n"
+			"             -4 | -6 | -0 | -V[ersion] }\n");
 	fprintf(stderr, "LISTofOBJECTS := [ link ] [ address ] [ route ]\n");
 	exit(-1);
 }
-- 
2.18.0

[iproute PATCH 10/10] man: ss.8: Describe --events option

[Phil Sutter]

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 man/man8/ss.8 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man/man8/ss.8 b/man/man8/ss.8
index 28033d8f01dda..7a6572b173648 100644
--- a/man/man8/ss.8
+++ b/man/man8/ss.8
@@ -242,6 +242,9 @@ Print summary statistics. This option does not parse socket lists obtaining
 summary from various sources. It is useful when amount of sockets is so huge
 that parsing /proc/net/tcp is painful.
 .TP
+.B \-E, \-\-events
+Continually display sockets as they are destroyed
+.TP
 .B \-Z, \-\-context
 As the
 .B \-p
-- 
2.18.0

Re: [iproute PATCH 00/10] Review help texts and man pages

[Stephen Hemminger]

On Thu, 16 Aug 2018 12:27:52 +0200
Phil Sutter <phil@nwl.cc> wrote:

> This series fixes a number of issues identified by an automated scan
> over man pages and help texts.
> 
> Phil Sutter (10):
>   man: bridge.8: Document -oneline option
>   bridge: trivial: Make help text consistent
>   devlink: trivial: Make help text consistent
>   man: devlink.8: Document -verbose option
>   genl: Fix help text
>   man: ifstat.8: Document --json and --pretty options
>   ip: Add missing -M flag to help text
>   man: rtacct.8: Fix nstat options
>   rtmon: List options in help text
>   man: ss.8: Describe --events option
> 
>  bridge/bridge.c    |  2 +-
>  devlink/devlink.c  |  2 +-
>  genl/genl.c        |  4 ++--
>  ip/ip.c            |  2 +-
>  ip/rtmon.c         |  4 +++-
>  man/man8/bridge.8  | 15 ++++++++++++++-
>  man/man8/devlink.8 |  4 ++++
>  man/man8/ifstat.8  |  8 ++++++++
>  man/man8/rtacct.8  | 14 +++++++++-----
>  man/man8/ss.8      |  3 +++
>  10 files changed, 46 insertions(+), 12 deletions(-)
> 

Sure, applied. Had to do one bit of whitespace cleanup on genl.c

Re: [iproute PATCH 07/10] ip: Add missing -M flag to help text

[Phil Sutter]

Hi Stephen,
On Thu, Aug 16, 2018 at 12:27:59PM +0200, Phil Sutter wrote:
> Signed-off-by: Phil Sutter <phil@nwl.cc>
> ---
>  ip/ip.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Seems like this patch wasn't applied. Did you perhaps drop it by
accident?

Cheers, Phil