Message-ID: <ZJuChT7GPgEpORaQ@localhost>
Date: Wed, 28 Jun 2023 00:44:53 +0000
From: Bjarni Ingi Gislason <bjarniig@...net.is>
To: Stephen Hemminger <stephen@...workplumber.org>
Cc: netdev@...r.kernel.org
Subject: Re: tc.8:  some remarks and a patch for the manual

On Tue, Jun 27, 2023 at 10:38:49AM -0700, Stephen Hemminger wrote:
> On Sat, 24 Jun 2023 21:43:21 +0000
> Bjarni Ingi Gislason <bjarniig@...net.is> wrote:
> 
> > Package: iproute2
> > Version: 6.3.0
> > Severity: minor
> > Tags: patch
> > 
> > Dear Maintainer,
> > 
> > here are some notes and a patch.
> > 
> > The difference between the formatted outputs can be seen with:
> > 
> >   nroff -man <file1> > <out1>
> >   nroff -man <file2> > <out2>
> >   diff -u <out1> <out2>
> > 
> > and for groff, using
> > 
> > "groff -man -Z" instead of "nroff -man"
> 
> Overall this looks fine but:
> 1. Make the commit message more succinct and clearer, don't need to write a letter.
> 2. Lines with starting with # get ignored by git when committing
> 3. Missing Signed-Off-by which is required for all iproute2 patches.
> 
> Running checkpatch on this patch will show these things.

  Here is a simplified patch based on the latest "iproute2" repository.

  Output from "checkpatch.pl" when run in the "git/iproute2" directory
with the patch:

Must be run from the top-level dir. of a kernel tree

Patch:

>From fc0bd90193ff11babb96bf8ae5658177e3465aeb Mon Sep 17 00:00:00 2001
From: Bjarni Ingi Gislason <bjarniig@...net.is>
Date: Wed, 28 Jun 2023 00:30:51 +0000
Subject: [PATCH] iproute2/man/man8/tc.8: some editorial changes to the man
 page

  Improve the layout of the man page according to the "man-page(7)"
guidelines, the output of "mandoc -lint T", the output of
"groff -ww -z -rSTYLECHECK=3", that of a shell script, and typographical
conventions.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@...net.is>
---
 man/man8/tc.8 | 86 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 48 insertions(+), 38 deletions(-)

diff --git a/man/man8/tc.8 b/man/man8/tc.8
index d436d464..e9d5d566 100644
--- a/man/man8/tc.8
+++ b/man/man8/tc.8
@@ -18,7 +18,7 @@ tc \- show / manipulate traffic control settings
 \fIBLOCK_INDEX\fR ] qdisc
 [ qdisc specific parameters ]
 .P
-
+.
 .B tc
 .RI "[ " OPTIONS " ]"
 .B class [ add | change | replace | delete | show ] dev
@@ -29,7 +29,7 @@ tc \- show / manipulate traffic control settings
 \fIclass-id\fR ] qdisc
 [ qdisc specific parameters ]
 .P
-
+.
 .B tc
 .RI "[ " OPTIONS " ]"
 .B filter [ add | change | replace | delete | get ] dev
@@ -121,13 +121,13 @@ tc \- show / manipulate traffic control settings
 .P
 .ti 8
 .IR OPTIONS " := {"
-\fB[ -force ] -b\fR[\fIatch\fR] \fB[ filename ] \fR|
-\fB[ \fB-n\fR[\fIetns\fR] name \fB] \fR|
-\fB[ \fB-N\fR[\fIumeric\fR] \fB] \fR|
-\fB[ \fB-nm \fR| \fB-nam\fR[\fIes\fR] \fB] \fR|
-\fB[ \fR{ \fB-cf \fR| \fB-c\fR[\fIonf\fR] \fR} \fB[ filename ] \fB] \fR
-\fB[ -t\fR[imestamp\fR] \fB\] \fR| \fB[ -t\fR[short\fR] \fR| \fB[
--o\fR[neline\fR] \fB]\fR }
+\fB[ \-force ] \-b\fR[\fIatch\fR] \fB[ filename ] \fR|
+\fB[ \fB\-n\fR[\fIetns\fR] name \fB] \fR|
+\fB[ \fB\-N\fR[\fIumeric\fR] \fB] \fR|
+\fB[ \fB\-nm \fR| \fB\-nam\fR[\fIes\fR] \fB] \fR|
+\fB[ \fR{ \fB\-cf \fR| \fB\-c\fR[\fIonf\fR] \fR} \fB[ filename ] \fB]\fR
+\fB[ \-t\fR[imestamp\fR] \fB] \fR| \fB[ \-t\fR[short\fR] \fR| \fB[
+\-o\fR[neline\fR] \fB]\fR }
 
 .ti 8
 .IR FORMAT " := {"
@@ -147,9 +147,10 @@ of the following:
 
 .TP
 SHAPING
-When traffic is shaped, its rate of transmission is under control. Shaping may
-be more than lowering the available bandwidth - it is also used to smooth out
-bursts in traffic for better network behaviour. Shaping occurs on egress.
+When traffic is shaped, its rate of transmission is under control.
+Shaping may be more than lowering the available bandwidth \(en
+it is also used to smooth out bursts in traffic for better network
+behaviour. Shaping occurs on egress.
 
 .TP
 SCHEDULING
@@ -186,9 +187,9 @@ First In, First Out queue. It does however store traffic when the network interf
 can't handle it momentarily.
 
 .SH CLASSES
-Some qdiscs can contain classes, which contain further qdiscs - traffic may
+Some qdiscs can contain classes, which contain further qdiscs \(en traffic may
 then be enqueued in any of the inner qdiscs, which are within the
-.B classes.
+.BR classes .
 When the kernel tries to dequeue a packet from such a
 .B classful qdisc
 it can come from any of the classes. A qdisc may for example prioritize
@@ -207,7 +208,7 @@ available. This differs per qdisc.
 
 It is important to notice that filters reside
 .B within
-qdiscs - they are not masters of what happens.
+qdiscs \(en they are not masters of what happens.
 
 The available filters are:
 .TP
@@ -326,7 +327,8 @@ separate queue with less priority so that bulk traffic does not affect the
 latency of critical traffic.
 .TP
 ingress
-This is a special qdisc as it applies to incoming traffic on an interface, allowing for it to be filtered and policed.
+This is a special qdisc as it applies to incoming traffic on an
+interface, allowing for it to be filtered and policed.
 .TP
 mqprio
 The Multiqueue Priority Qdisc is a simple queuing discipline that allows
@@ -427,7 +429,12 @@ bandwidth-sharing bands to implement the transmission selection described in
 802.1Qaz.
 .TP
 HFSC
-Hierarchical Fair Service Curve guarantees precise bandwidth and delay allocation for leaf classes and allocates excess bandwidth fairly. Unlike HTB, it makes use of packet dropping to achieve low delays which interactive sessions benefit from.
+Hierarchical Fair Service Curve guarantees precise bandwidth
+and delay allocation for leaf classes and allocates excess bandwidth
+fairly.
+Unlike HTB,
+it makes use of packet dropping to achieve low delays
+which interactive sessions benefit from.
 .TP
 HTB
 The Hierarchy Token Bucket implements a rich linksharing hierarchy of
@@ -655,8 +662,9 @@ parameter.
 
 .TP
 delete
-A qdisc can be deleted by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
-are automatically deleted, as well as any filters attached to them.
+A qdisc can be deleted by specifying its handle, which may also be 'root'.
+All subclasses and their leaf qdiscs are automatically deleted,
+as well as any filters attached to them.
 
 .TP
 change
@@ -704,9 +712,10 @@ read commands from provided file or standard input and invoke them.
 First failure will cause termination of tc.
 
 .TP
-.BR "\-force"
+.B \-force
 don't terminate tc on errors in batch mode.
-If there were any errors during execution of the commands, the application return code will be non zero.
+If there were any errors during execution of the commands,
+the application return code will be non zero.
 
 .TP
 .BR "\-o" , " \-oneline"
@@ -729,15 +738,15 @@ to the specified network namespace
 Actually it just simplifies executing of:
 
 .B ip netns exec
-.IR NETNS
+.I NETNS
 .B tc
-.RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
+.RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " |"
 .BR help " }"
 
 to
 
 .B tc
-.RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
+.RI "\-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " |"
 .BR help " }"
 
 .TP
@@ -748,7 +757,7 @@ converting it to human readable name.
 .TP
 .BR "\-cf" , " \-conf " <FILENAME>
 specifies path to the config file. This option is used in conjunction with other options (e.g.
-.BR -nm ")."
+.BR \-nm ")."
 
 .TP
 .BR "\-t", " \-timestamp"
@@ -781,15 +790,15 @@ for u32 filter, decode offset and mask values to equivalent filter commands base
 In JSON output, add whitespace to improve readability.
 
 .TP
-.BR "\-iec"
-print rates in IEC units (ie. 1K = 1024).
+.B \-iec
+print rates in IEC units (i.e. 1\~K = 1024).
 
 .TP
 .BR "\-g", " \-graph"
 shows classes as ASCII graph. Prints generic stats info under each class if
-.BR "-s"
+.B \-s
 option was specified. Classes can be filtered only by
-.BR "dev"
+.B dev
 option.
 
 .TP
@@ -806,7 +815,7 @@ precedence. This flag is ignored if
 is also given.
 
 .TP
-.BR "\-j", " \-json"
+.BR \-j ", " \-json
 Display results in JSON format.
 
 .TP
@@ -814,7 +823,7 @@ Display results in JSON format.
 resolve class name from
 .B /etc/iproute2/tc_cls
 file or from file specified by
-.B -cf
+.B \-cf
 option. This file is just a mapping of
 .B classid
 to class name:
@@ -838,13 +847,13 @@ to class name:
 .RS
 .B tc
 will not fail if
-.B -nm
+.B \-nm
 was specified without
-.B -cf
+.B \-cf
 option but
 .B /etc/iproute2/tc_cls
 file does not exist, which makes it possible to pass
-.B -nm
+.B \-nm
 option for creating
 .B tc
 alias.
@@ -857,13 +866,13 @@ cookie, etc.) and stats. This option is currently only supported by
 .BR "tc filter show " and " tc actions ls " commands.
 
 .SH "EXAMPLES"
-.PP
-tc -g class show dev eth0
+.
+tc \-g class show dev eth0
 .RS 4
 Shows classes as ASCII graph on eth0 interface.
 .RE
 .PP
-tc -g -s class show dev eth0
+tc \-g \-s class show dev eth0
 .RS 4
 Shows classes as ASCII graph with stats info under each class.
 .RE
@@ -905,7 +914,8 @@ was written by Alexey N. Kuznetsov and added in Linux 2.2.
 .BR tc-tcindex (8),
 .BR tc-u32 (8),
 .br
-.RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@...r.kernel.org>
+.RB "User documentation at " http://lartc.org/ ", \
+but please direct bugreports and patches to: " <netdev@...r.kernel.org>
 
 .SH AUTHOR
 Manpage maintained by bert hubert (ahu@...a.nl)
-- 
2.40.1

Powered by blists - more mailing lists