dcb.8: some remarks and editorial changes for this manual

dcb.8: some remarks and editorial changes for this manual

[Bjarni Ingi Gislason]

  The man page is from Debian:

Package: iproute2
Version: 6.11.0-1
Severity: minor
Tags: patch

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

-.-

Signed-off-by: Bjarni Ingi Gislason <bjarniig@simnet.is>

diff --git a/dcb.8 b/dcb.8.new
index a1d6505..2202224 100644
--- a/dcb.8
+++ b/dcb.8.new
@@ -2,74 +2,74 @@
 .SH NAME
 dcb \- show / manipulate DCB (Data Center Bridging) settings
 .SH SYNOPSIS
-.sp
 .ad l
 .in +8
 
 .ti -8
 .B dcb
-.RI "[ " OPTIONS " ] "
+.RI "[ " OPTIONS " ]"
 .RB "{ " app " | " buffer " | " ets " | " maxrate " | " pfc " }"
 .RI "{ " COMMAND " | " help " }"
 .sp
 
 .ti -8
 .B dcb
-.RB "[ " -force " ] "
-.BI "-batch " filename
+.RB "[ " \-force " ]"
+.BI "\-batch " filename
 .sp
 
 .ti -8
 .B dcb
-.RI "[ " OPTIONS " ] "
+.RI "[ " OPTIONS " ]"
 .B help
 .sp
 
 .SH OPTIONS
 
 .TP
-.BR "\-n" , " \--netns " <NETNS>
+.BR "\-n" , " \-\-netns " <NETNS>
 switches
 .B dcb
 to the specified network namespace
 .IR NETNS .
 
 .TP
-.BR "\-V" , " --Version"
+.BR "\-V" , " \-\-Version"
 Print the version of the
 .B dcb
 utility and exit.
 
 .TP
-.BR "\-b", " --batch " <FILENAME>
-Read commands from provided file or standard input and invoke them. First
-failure will cause termination of dcb.
+.BR "\-b", " \-\-batch " <FILENAME>
+Read commands from provided file or standard input and invoke them.
+First failure will cause termination of dcb.
 
 .TP
-.BR "\-f", " --force"
-Don't terminate dcb on errors in batch mode. If there were any errors during
-execution of the commands, the application return code will be non zero.
+.BR "\-f", " \-\-force"
+Don't terminate dcb on errors in batch mode.
+If there were any errors during execution of the commands,
+the application return code will be non zero.
 
 .TP
-.BR "\-i" , " --iec"
-When showing rates, use ISO/IEC 1024-based prefixes (Ki, Mi, Bi) instead of
-the 1000-based ones (K, M, B).
+.BR "\-i" , " \-\-iec"
+When showing rates, use ISO/IEC 1024-based prefixes (Ki, Mi, Gi) instead of
+the 1000-based ones (K, M, G).
 
 .TP
-.BR "\-j" , " --json"
+.BR "\-j" , " \-\-json"
 Generate JSON output.
 
 .TP
-.BR "\-N" , " --Numeric"
+.BR "\-N" , " \-\-Numeric"
 If the subtool in question translates numbers to symbolic names in some way,
 suppress this translation.
 
 .TP
-.BR "\-p" , " --pretty"
-When combined with -j generate a pretty JSON output.
+.BR "\-p" , " \-\-pretty"
+When combined with \-j generate a pretty JSON output.
 
 .TP
-.BR "\-s" , " --statistics"
+.BR "\-s" , " \-\-statistics"
 If the object in question contains any statistical counters, shown them as
 part of the "show" output.
 
@@ -77,59 +77,66 @@ part of the "show" output.
 
 .TP
 .B app
-- Configuration of application priority table
+\(en Configuration of application priority table
 
 .TP
 .B buffer
-- Configuration of port buffers
+\(en Configuration of port buffers
 
 .TP
 .B ets
-- Configuration of ETS (Enhanced Transmission Selection)
+\(en Configuration of ETS (Enhanced Transmission Selection)
 
 .TP
 .B maxrate
-- Configuration of per-TC maximum transmit rate
+\(en Configuration of per-TC maximum transmit rate
 
 .TP
 .B pfc
-- Configuration of PFC (Priority-based Flow Control)
+\(en Configuration of PFC (Priority-based Flow Control)
 
 .SH COMMANDS
 
-A \fICOMMAND\fR specifies the action to perform on the object. The set of
-possible actions depends on the object type. As a rule, it is possible to
+A \fICOMMAND\fR specifies the action to perform on the object.
+The set of possible actions depends on the object type.
+As a rule, it is possible to
 .B show
 objects and to invoke topical
-.B help,
+.BR help ,
 which prints a list of available commands and argument syntax conventions.
 
 .SH ARRAY PARAMETERS
 
 Like commands, specification of parameters is in the domain of individual
-objects (and their commands) as well. However, much of the DCB interface
-revolves around arrays of fixed size that specify one value per some key, such
-as per traffic class or per priority. There is therefore a single syntax for
-adjusting elements of these arrays. It consists of a series of
-\fIKEY\fB:\fIVALUE\fR pairs, where the meaning of the individual keys and values
-depends on the parameter.
+objects (and their commands) as well.
+However, much of the DCB interface
+revolves around arrays of fixed size that specify one value per some key,
+such as per traffic class or per priority.
+There is therefore a single syntax for adjusting elements of these arrays.
+It consists of a series of \fIKEY\fB:\fIVALUE\fR pairs,
+where the meaning of the individual keys and values depends on the parameter.
 
 The elements are evaluated in order from left to right, and the latter ones
-override the earlier ones. The elements that are not specified on the command
+override the earlier ones.
+The elements that are not specified on the command
 line are queried from the kernel and their current value is retained.
 
 As an example, take a made-up parameter tc-juju, which can be set to charm
-traffic in a given TC with either good luck or bad luck. \fIKEY\fR can therefore
-be 0..7 (as is usual for TC numbers in DCB), and \fIVALUE\fR either of
-\fBnone\fR, \fBgood\fR, and \fBbad\fR. An example of changing a juju value of
-TCs 0 and 7, while leaving all other intact, would then be:
+traffic in a given TC with either good luck or bad luck.
+\fIKEY\fR can therefore be 0..7
+(as is usual for TC numbers in DCB),
+and \fIVALUE\fR either of \fBnone\fR, \fBgood\fR, and \fBbad\fR.
+An example of changing a juju value of TCs 0 and 7,
+while leaving all other intact, would then be:
 
 .P
 # dcb foo set dev eth0 tc-juju 0:good 7:bad
 
 A special key, \fBall\fR, is recognized which sets the same value to all array
-elements. This can be combined with the usual single-element syntax. E.g. in the
-following, the juju of all keys is set to \fBnone\fR, except 0 and 7, which have
+elements.
+This can be combined with the usual single-element syntax.
+E.g., in the following,
+the juju of all keys is set to \fBnone\fR, except 0 and 7, which have
 other values:
 
 .P
@@ -146,7 +153,6 @@ Exit status is 0 if command was successful or a positive integer upon failure.
 .BR dcb-maxrate (8),
 .BR dcb-pfc (8),
 .BR dcb-rewr (8)
-.br
 
 .SH REPORTING BUGS
 Report any bugs to the Network Developers mailing list

Re: dcb.8: some remarks and editorial changes for this manual

[Stephen Hemminger]

On Sun, 3 Nov 2024 01:27:16 +0000
Bjarni Ingi Gislason <bjarniig@simnet.is> wrote:

>   The man page is from Debian:
> 
> Package: iproute2
> Version: 6.11.0-1
> Severity: minor
> Tags: patch
> 
>   Improve the layout of the man page according to the "man-page(7)"
> guidelines, the output of "mandoc -lint T", the output of
> "groff -mandoc -t -ww -b -z", that of a shell script, and typographical
> conventions.
> 
> -.-
> 
> Signed-off-by: Bjarni Ingi Gislason <bjarniig@simnet.is>

Thanks will pick this up in iproute2 release

Re: dcb.8: some remarks and editorial changes for this manual

[Stephen Hemminger]

On Sun, 3 Nov 2024 01:27:16 +0000
Bjarni Ingi Gislason <bjarniig@simnet.is> wrote:

>   The man page is from Debian:
> 
> Package: iproute2
> Version: 6.11.0-1
> Severity: minor
> Tags: patch
> 
>   Improve the layout of the man page according to the "man-page(7)"
> guidelines, the output of "mandoc -lint T", the output of
> "groff -mandoc -t -ww -b -z", that of a shell script, and typographical
> conventions.
> 
> -.-
> 
> Signed-off-by: Bjarni Ingi Gislason <bjarniig@simnet.is>
> 
> diff --git a/dcb.8 b/dcb.8.new
> index a1d6505..2202224 100644
> --- a/dcb.8
> +++ b/dcb.8.new
> @@ -2,74 +2,74 @@

The format of these patches does not allow for simple application to
the iproute tree. Patches should be on the same file. All your patches
have .new which won't work.

The simplest way to handle this would be:
 - take a git branch on your local repo
 - do the work there and commit each change
 - when ready to:
     $ git send-email --subject-prefix 'PATCH v2 iproute' --cover-letter main



A normal patch looks like this one.


diff --git a/MAINTAINERS b/MAINTAINERS
index 1b49d69e..84931abd 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -30,6 +30,7 @@ M: Roopa Prabhu <roopa@nvidia.com>
 M: Nikolay Aleksandrov <razor@blackwall.org>
 L: bridge@lists.linux-foundation.org (moderated for non-subscribers)
 F: bridge/*
+F: ip/iplink_bridge*
 
 Data Center Bridging - dcb
 M: Petr Machata <me@pmachata.org>
--