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

[Bjarni Ingi Gislason <bjarniig@simnet.is>]

[-- Attachment #1: Type: text/plain, Size: 3316 bytes --]

  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.

-.-

  Output from a script "chk_manual" is in the attachment.

-.-

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


--- dcb-apptrust.8	2024-11-04 19:51:38.581034458 +0000
+++ dcb-apptrust.8.new	2024-11-04 20:04:44.751223062 +0000
@@ -3,33 +3,33 @@
 dcb-apptrust \- show / configure per-selector trust and trust order of the
 application priority table of the DCB (Data Center Bridging) subsystem.
 .SH SYNOPSIS
-.sp
 .ad l
 .in +8
 
 .ti -8
 .B dcb
-.RI "[ " OPTIONS " ] "
+.RI "[ " OPTIONS " ]"
 .B apptrust
 .RI "{ " COMMAND " | " help " }"
 .sp
 
 .ti -8
 .B dcb apptrust show dev
-.RI DEV
+.I DEV
 .RB "[ " order " ]"
 
 .ti -8
 .B dcb apptrust set dev
-.RI DEV
-.RB "[ " order "
+.I DEV
+.RB "[ " order
 .IR "SEL-LIST" " ]"
 
 .ti -8
 .IR SEL-LIST " := [ " SEL-LIST " ] " SEL
 
 .ti -8
-.IR SEL " := { " ethtype " | " stream-port " | " dgram-port " | " port " | " dscp " | " pcp " } "
+.IR SEL " := { " ethtype " | " stream-port " | " dgram-port " | " port " | " \
+dscp " | " pcp " }"
 
 .SH DESCRIPTION
 
@@ -40,10 +40,13 @@ Application Priority Table, see
 for details on how to configure app table entries.
 
 Selector trust can be used by the
-software stack, or drivers (most likely the latter), when querying the APP
-table, to determine if an APP entry should take effect, or not. Additionally, the
-order of the trusted selectors will dictate which selector should take
-precedence, in the case of multiple different APP table selectors being present.
+software stack, or drivers (most likely the latter),
+when querying the APP table,
+to determine if an APP entry should take effect, or not.
+Additionally,
+the order of the trusted selectors will dictate which selector should take
+precedence,
+in the case of multiple different APP table selectors being present.
 
 .SH COMMANDS
 
@@ -53,25 +56,27 @@ Display all trusted selectors.
 
 .TP
 .B set
-Set new list of trusted selectors. Empty list is effectively the same as
-removing trust entirely.
+Set new list of trusted selectors.
+Empty list is effectively the same as removing trust entirely.
 
 .SH PARAMETERS
 
-The following describes only the write direction, i.e. as used with the
-\fBset\fR command. For the \fBshow\fR command, the parameter name is to be used
-as a simple keyword without further arguments. This instructs the tool to show
-the values of a given parameter.
+The following describes only the write direction, i.e.,
+as used with the \fBset\fR command.
+For the \fBshow\fR command,
+the parameter name is to be used as a simple keyword without further
+arguments.
+This instructs the tool to show the values of a given parameter.
 
 .TP
 .B order \fISEL-LIST
-\fISEL-LIST\fR is a space-separated list of selector names. Possible selector
-values are:
-.B ethtype,
-.B stream-port,
-.B dgram-port,
-.B port,
-.B dscp,
+\fISEL-LIST\fR is a space-separated list of selector names.
+Possible selector values are:
+.BR ethtype ,
+.BR stream-port ,
+.BR dgram-port ,
+.BR port ,
+.BR dscp ,
 and
 .B pcp
 

[-- Attachment #2: chk_man.err.dcb-apptrust.8 --]
[-- Type: text/plain, Size: 4707 bytes --]

  Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)

[gn]roff -mandoc -t -ww -b -z -K utf8  <man page>

  The same goes for man pages that are used as an input.

  For a style guide use

  mandoc -T lint

-.-

  So any 'generator' should check its products with the above mentioned
'groff', 'mandoc',  and additionally with 'nroff ...'.

  This is just a simple quality control measure.

  The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.

  Common defects:

  Input text line longer than 80 bytes.

  Not removing trailing spaces (in in- and output).
  The reason for these trailing spaces should be found and eliminated.

  Not beginning each input sentence on a new line.
Lines should thus be shorter.

  See man-pages(7), item 'semantic newline'.

-.-

The difference between the formatted output of the original and patched file
can be seen with:

  nroff -mandoc <file1> > <out1>
  nroff -mandoc <file2> > <out2>
  diff -u <out1> <out2>

and for groff, using

"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "

instead of 'nroff -mandoc'

  Add the option '-t', if the file contains a table.

  Read the output of 'diff -u' with 'less -R' or similar.

-.-.

  If 'man' (man-db) is used to check the manual for warnings,
the following must be set:

  The option "-warnings=w"

  The environmental variable:

export MAN_KEEP_STDERR=yes (or any non-empty value)

  or

  (produce only warnings):

export MANROFFOPT="-ww -b -z"

export MAN_KEEP_STDERR=yes (or any non-empty value)

-.-.

Output from "mandoc -T lint dcb-apptrust.8": (possibly shortened list)

mandoc: dcb-apptrust.8:6:2: WARNING: skipping paragraph macro: sp after SH
mandoc: dcb-apptrust.8:25:16: STYLE: unterminated quoted argument
mandoc: dcb-apptrust.8:44:81: STYLE: input text line longer than 80 bytes: table, to determine ...

-.-.


Use the correct macro for the font change of a single argument or
split the argument into two.

19:.RI DEV
24:.RI DEV

-.-.

Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.

61:The following describes only the write direction, i.e. as used with the

-.-.

Wrong distance between sentences in the input file.

  Separate the sentences and subordinate clauses; each begins on a new
line.  See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").

  The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.

Remember coding: Only one command ("sentence") on each (logical) line.

E-mail: Easier to quote exactly the relevant lines.

Generally: Easier to edit the sentence.

Patches: Less unaffected text.

Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.

44:table, to determine if an APP entry should take effect, or not. Additionally, the
56:Set new list of trusted selectors. Empty list is effectively the same as
61:The following describes only the write direction, i.e. as used with the
62:\fBset\fR command. For the \fBshow\fR command, the parameter name is to be used
63:as a simple keyword without further arguments. This instructs the tool to show
68:\fISEL-LIST\fR is a space-separated list of selector names. Possible selector

-.-.

Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.

Line 32, length 97

.IR SEL " := { " ethtype " | " stream-port " | " dgram-port " | " port " | " dscp " | " pcp " } "

Line 44, length 81

table, to determine if an APP entry should take effect, or not. Additionally, the


-.-.

Split a punctuation from a single argument, if a two-font macro is meant

70:.B ethtype,
71:.B stream-port,
72:.B dgram-port,
73:.B port,
74:.B dscp,

-.-.

No space is needed before a quote (") at the end of a line

12:.RI "[ " OPTIONS " ] "
25:.RB "[ " order "
32:.IR SEL " := { " ethtype " | " stream-port " | " dgram-port " | " port " | " dscp " | " pcp " } "

-.-.

Output from "test-groff  -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":

troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':709: macro 'RI'
troff: backtrace: file '<stdin>':12
troff:<stdin>:12: warning: trailing space in the line
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':679: macro 'IR'
troff: backtrace: file '<stdin>':32
troff:<stdin>:32: warning: trailing space in the line

-.-.