Package: groff
Version: upstream
Severity: minor
Dear Maintainer,
* What led up to the situation?
Checking for defects with
[test-]groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
troff: backtrace: file '<stdin>':184
troff:<stdin>:184: warning: trailing space in the line
troff: backtrace: file '<stdin>':188
troff:<stdin>:188: warning: trailing space in the line
troff: backtrace: file '<stdin>':189
troff:<stdin>:189: warning: trailing space in the line
* What outcome did you expect instead?
No output (warnings).
-.-
General remarks and further material (declared as a "diff" file) are in the
attachments.
Any program (person), that produces man pages, should check its content for
defects by using
groff -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' 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 errors:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence
(that is not confined to a markup)
in the first column.
Line length should thus be reduced.
-.-
The difference between the formatted outputs 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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint grolbp.1.man": (possibly shortened list)
mandoc: grolbp.1.man:92:2: WARNING: skipping paragraph macro: PP empty
mandoc: grolbp.1.man:102:2: WARNING: skipping paragraph macro: PP empty
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':184
troff:<stdin>:184: warning: trailing space in the line
troff: backtrace: file '<stdin>':188
troff:<stdin>:188: warning: trailing space in the line
troff: backtrace: file '<stdin>':189
troff:<stdin>:189: warning: trailing space in the line
In current groff (1.23.0), table is rendered thus
+---------------+---------+--------+----------+--------------+
| Typeface | Roman | Bold | Italic | Bold-Italic |
+---------------+---------+--------+----------+--------------+
| Dutch | TR | TB | TI | TBI |
+---------------+---------+--------+----------+--------------+
| Swiss | HR | HB | HI | HBI |
+---------------+---------+--------+----------+--------------+
| Swiss Narrow | HNR | HNB | HNI | HNBI |
+---------------+---------+--------+----------+--------------+
| Courier | CR | CB | CI | |
+---------------+---------+--------+----------+--------------+
| Elite | ER | EB | EI | |
+---------------+---------+--------+----------+--------------+
There is thus no need to format all columns in the header line as
"centered" (C).
That will also eliminate the creation of a trailing space in the last header
column.
Adding a '\&' as a data in the last (empty) column in the last two lines
will also eliminate unnecessary trailing space
(which is removed each time this man page is rendered,
instead of never creating it;
not reported by the upstream version).
