Package: exim4-base
Version: 4.98-2
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff: backtrace: '<stdin>':11: macro 'Vb'
troff: backtrace: file '<stdin>':67
troff:<stdin>:67: warning: font name 'CW' is deprecated
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.11.5-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages exim4-base depends on:
ii adduser 3.137
ii anacron 2.3-40
ii cron [cron-daemon] 3.0pl1-189
ii debconf [debconf-2.0] 1.5.87
ii exim4-config [exim4-config-2] 4.98-2
ii libc6 2.40-3
ii libdb5.3t64 5.3.28+dfsg2-9
ii libfile-fcntllock-perl 0.22-4+b4
ii netbase 6.4
ii perl 5.40.0-6
Versions of packages exim4-base recommends:
pn bsd-mailx | mailx <none>
ii psmisc 23.7-1
Versions of packages exim4-base suggests:
pn exim4-doc-html | exim4-doc-info <none>
pn eximon4 <none>
ii file 1:5.45-3+b1
ii mutt [mail-reader] 2.2.13-1
ii neomutt [mail-reader] 20241002+dfsg-1
ii openssl 3.3.2-2
pn spf-tools-perl <none>
pn swaks <none>
-- debconf information excluded
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 eximstats.8": (possibly shortened list)
mandoc: eximstats.8:91:84: STYLE: input text line longer than 80 bytes: Output
the results i...
mandoc: eximstats.8:163:84: STYLE: input text line longer than 80 bytes: May be
combined with...
mandoc: eximstats.8:167:85: STYLE: input text line longer than 80 bytes: May be
combined with...
mandoc: eximstats.8:171:83: STYLE: input text line longer than 80 bytes: May be
combined with...
mandoc: eximstats.8:174:81: STYLE: input text line longer than 80 bytes: Look
for the specifi...
mandoc: eximstats.8:208:2: WARNING: empty block: RS
mandoc: eximstats.8:229:92: STYLE: input text line longer than 80 bytes: To
install these, do...
mandoc: eximstats.8:256:97: STYLE: input text line longer than 80 bytes: easier
to trap error...
-.-.
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.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
69:\& eximstats \-merge [Options] report.1.txt report.2.txt ... >
weekly_report.txt
78:Output the results in plain text. Filename '\-' for STDOUT is accepted.
84:Output the results in HTML. Filename '\-' for STDOUT is accepted.
91:Output the results in Excel compatible format. Filename '\-' for STDOUT is
accepted.
96:histogram divisions per hour. The default is 1, and
97:0 suppresses histograms. Valid values are:
140:\&\fIlist\fR is an optional list of times. Eg \-show_dt1,2,4,8 will show
145:Show the receipt times for all the messages. The receipt time is
152:\&\fIlist\fR is an optional list of times. Eg \-show_rt1,2,4,8 will show
157:Show results by sending host. This may be combined with
158:\&\fB\-bydomain\fR and/or \fB\-byemail\fR and/or \fB\-byedomain\fR. If none
of these options
175:This option can be specified multiple times. Eg:
182:This option allows eximstats to merge old eximstat reports together. Eg:
251:Specify that it's OK to not find any valid log lines. Without this
255:Debug flag. This outputs the \fBeval()\fR'd parser onto STDOUT which makes
it
256:easier to trap errors in the eval section. Remember to add 1 to the line
numbers to allow for the
261:analysis of the messages processed. By default, a text
263:using flags. See the help (\fB\-help\fR) to learn
273:immediately delivered. Fixing this could be tricky...
275:Merging of xls files is not (yet) possible. Be free to implement :)
-.-.
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 91, length 84
Output the results in Excel compatible format. Filename '\-' for STDOUT is
accepted.
Line 158, length 92
\&\fB\-bydomain\fR and/or \fB\-byemail\fR and/or \fB\-byedomain\fR. If none of
these options
Line 163, length 84
May be combined with \fB\-byhost\fR and/or \fB\-byemail\fR and/or
\fB\-byedomain\fR.
Line 167, length 85
May be combined with \fB\-byhost\fR and/or \fB\-bydomain\fR and/or
\fB\-byedomain\fR.
Line 171, length 83
May be combined with \fB\-byhost\fR and/or \fB\-bydomain\fR and/or
\fB\-byemail\fR.
Line 174, length 81
Look for the specified pattern and count the number of lines in which it
appears.
Line 229, length 92
To install these, download and unpack them, then use the normal perl
installation procedure:
Line 239, length 85
\&\f(CW\*(C`apt\-get install libgd\-perl libgd\-text\-perl
libgd\-graph\-perl\*(C'\fR
Line 256, length 97
easier to trap errors in the eval section. Remember to add 1 to the line
numbers to allow for the
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
7:.if t .sp 0.5v
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: '<stdin>':11: macro 'Vb'
troff: backtrace: file '<stdin>':67
troff:<stdin>:67: warning: font name 'CW' is deprecated
--- eximstats.8 2024-11-09 17:29:04.450102277 +0000
+++ eximstats.8.new 2024-11-09 18:00:52.661298675 +0000
@@ -88,13 +88,15 @@ Output the results in Excel compatible F
Requires the Spreadsheet::WriteExcel CPAN module.
.IP \fB\-xls\fR=\fIfilename\fR 4
.IX Item "-xls=filename"
-Output the results in Excel compatible format. Filename '\-' for STDOUT is
accepted.
+Output the results in Excel compatible format.
+Filename '\-' for STDOUT is accepted.
.SS Options:
.IX Subsection "Options:"
.IP \fB\-h\fR\fInumber\fR 4
.IX Item "-hnumber"
-histogram divisions per hour. The default is 1, and
-0 suppresses histograms. Valid values are:
+histogram divisions per hour.
+The default is 1, and 0 suppresses histograms.
+Valid values are:
.Sp
0, 1, 2, 3, 5, 10, 15, 20, 30 or 60.
.IP \fB\-ne\fR 4
@@ -137,9 +139,10 @@ Show the delivery times (\fBDT\fR)for al
Exim must have been configured to use the +deliver_time logging option
for this option to work.
.Sp
-\&\fIlist\fR is an optional list of times. Eg \-show_dt1,2,4,8 will show
-the number of messages with delivery times under 1 second, 2 seconds, 4
seconds,
-8 seconds, and over 8 seconds.
+\&\fIlist\fR is an optional list of times.
+E.g., \-show_dt1,2,4,8 will show
+the number of messages with delivery times under 1 second,
+2 seconds, 4 seconds, 8 seconds, and over 8 seconds.
.IP \fB\-show_rt\fR\fIlist\fR 4
.IX Item "-show_rtlist"
Show the receipt times for all the messages. The receipt time is
@@ -149,37 +152,45 @@ These figures will be skewed by pipeline
Exim must have been configured to use the +queue_time_overall logging option
for this option to work.
.Sp
-\&\fIlist\fR is an optional list of times. Eg \-show_rt1,2,4,8 will show
+\&\fIlist\fR is an optional list of times.
+E.g., \-show_rt1,2,4,8 will show
the number of messages with receipt times under 1 second, 2 seconds, 4 seconds,
8 seconds, and over 8 seconds.
.IP \fB\-byhost\fR 4
.IX Item "-byhost"
-Show results by sending host. This may be combined with
-\&\fB\-bydomain\fR and/or \fB\-byemail\fR and/or \fB\-byedomain\fR. If none of
these options
-are specified, then \fB\-byhost\fR is assumed as a default.
+Show results by sending host.
+This may be combined with
+\&\fB\-bydomain\fR and/or \fB\-byemail\fR and/or \fB\-byedomain\fR.
+If none of these options are specified,
+then \fB\-byhost\fR is assumed as a default.
.IP \fB\-bydomain\fR 4
.IX Item "-bydomain"
Show results by sending domain.
-May be combined with \fB\-byhost\fR and/or \fB\-byemail\fR and/or
\fB\-byedomain\fR.
+May be combined with \fB\-byhost\fR and/or \fB\-byemail\fR and/or
+\fB\-byedomain\fR.
.IP \fB\-byemail\fR 4
.IX Item "-byemail"
Show results by sender's email address.
-May be combined with \fB\-byhost\fR and/or \fB\-bydomain\fR and/or
\fB\-byedomain\fR.
+May be combined with \fB\-byhost\fR and/or \fB\-bydomain\fR
+and/or \fB\-byedomain\fR.
.IP "\fB\-byemaildomain\fR or \fB\-byedomain\fR" 4
.IX Item "-byemaildomain or -byedomain"
Show results by sender's email domain.
May be combined with \fB\-byhost\fR and/or \fB\-bydomain\fR and/or
\fB\-byemail\fR.
.IP "\fB\-pattern\fR \fIDescription\fR \fI/Pattern/\fR" 4
.IX Item "-pattern Description /Pattern/"
-Look for the specified pattern and count the number of lines in which it
appears.
-This option can be specified multiple times. Eg:
+Look for the specified pattern and
+count the number of lines in which it appears.
+This option can be specified multiple times.
+E.g.:
.Sp
.Vb 1
\& \-pattern \*(AqRefused connections\*(Aq \*(Aq/refused connection/\*(Aq
.Ve
.IP \fB\-merge\fR 4
.IX Item "-merge"
-This option allows eximstats to merge old eximstat reports together. Eg:
+This option allows eximstats to merge old eximstat reports together.
+E.g.:
.Sp
.Vb 9
\& eximstats mainlog.sun > report.sun.txt
@@ -205,8 +216,6 @@ This will be towards the ends of the lis
The order of items in the top \fIn\fR lists may vary when the data volumes
round to the same value.
.RE
-.RS 4
-.RE
.IP \fB\-charts\fR 4
.IX Item "-charts"
Create graphical charts to be displayed in HTML output.
@@ -226,7 +235,8 @@ from http://www.cpan.org/modules/01modul
.RS 4
.PD
.Sp
-To install these, download and unpack them, then use the normal perl
installation procedure:
+To install these, download and unpack them,
+then use the normal perl installation procedure:
.Sp
.Vb 4
\& perl Makefile.PL
@@ -248,20 +258,22 @@ Specify the relative directory for the "
the charts
.IP \fB\-emptyok\fR 4
.IX Item "-emptyok"
-Specify that it's OK to not find any valid log lines. Without this
-we will output an error message if we don't find any.
+Specify that it's OK to not find any valid log lines.
+Without this we will output an error message if we don't find any.
.IP \fB\-d\fR 4
.IX Item "-d"
-Debug flag. This outputs the \fBeval()\fR'd parser onto STDOUT which makes it
-easier to trap errors in the eval section. Remember to add 1 to the line
numbers to allow for the
-title!
+Debug flag.
+This outputs the \fBeval()\fR'd parser onto STDOUT which makes it
+easier to trap errors in the eval section.
+Remember to add 1 to the line numbers to allow for the title!
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Eximstats parses exim mainlog and syslog files to output a statistical
-analysis of the messages processed. By default, a text
-analysis is generated, but you can request other output formats
-using flags. See the help (\fB\-help\fR) to learn
-about how to create charts from the tables.
+analysis of the messages processed.
+By default, a text analysis is generated,
+but you can request other output formats using flags.
+See the help (\fB\-help\fR) to learn about how to create charts from the
+tables.
.SH AUTHOR
.IX Header "AUTHOR"
There is a website at https://www.exim.org/.
@@ -270,6 +282,8 @@ There is a website at https://www.exim.o
This program does not perfectly handle messages whose received
and delivered log lines are in different files, which can happen
when you have multiple mail servers and a message cannot be
-immediately delivered. Fixing this could be tricky...
+immediately delivered.
+Fixing this could be tricky...
.PP
-Merging of xls files is not (yet) possible. Be free to implement :)
+Merging of xls files is not (yet) possible.
+Be free to implement :)
