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

-.-.