Bug#1087135: exim_db.8: Some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Fri Nov 8 21:35:23 GMT 2024
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: file '<stdin>':51
troff:<stdin>:51: warning: trailing space in the line
troff: backtrace: file '<stdin>':140
troff:<stdin>:140: warning: trailing space in the line
troff: backtrace: file '<stdin>':152
troff:<stdin>:152: warning: trailing space in the line
* 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
-------------- next part --------------
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 exim_db.8": (possibly shortened list)
mandoc: exim_db.8:22:83: STYLE: input text line longer than 80 bytes: exim_db \- Exim's hi...
mandoc: exim_db.8:51:54: STYLE: whitespace at end of input line
mandoc: exim_db.8:140:13: STYLE: whitespace at end of input line
mandoc: exim_db.8:152:43: STYLE: whitespace at end of input line
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
51:the data for implementing the ratelimit ACL condition
140:those hosts.
152:databases is likely to keep on increasing.
-.-.
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.
N.B.
The number of lines affected can be too large to be in a patch.
76:transport). If the remote port is not the standard one (port 25), it is
104:since the first delivery failure. Information about a host that has been
136:needed, but others are not. For example, if all the MX hosts for a domain
137:are down, a retry record is created for each one. If the primary MX host
143:the hints databases. You should do this at a quiet time of day, because it
145:it does its work. Removing records from a DBM file does not normally make
147:space that is released. After an initial phase of increasing in size, the
182:This manual page needs a major re-work. If somebody knows better groff
-.-.
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 22, length 83
exim_db \- Exim's hint databases maintenance (exim_dumpdb, exim_fixdb, exim_tidydb)
-.-.
Use \(en (en-dash) for a dash between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
exim_db.8:120:In the former these appear as data in records keyed by host - they were
exim_db.8:121:messages that were waiting for that host - and in the latter they are the
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':51
troff:<stdin>:51: warning: trailing space in the line
troff: backtrace: file '<stdin>':140
troff:<stdin>:140: warning: trailing space in the line
troff: backtrace: file '<stdin>':152
troff:<stdin>:152: warning: trailing space in the line
-------------- next part --------------
--- exim_db.8 2024-11-08 20:40:14.440636102 +0000
+++ exim_db.8.new 2024-11-08 21:24:34.014193533 +0000
@@ -19,7 +19,8 @@
.\" \(oqthis text is enclosed in single quotes\(cq
.\" \(lqthis text is enclosed in double quotes\(rq
.SH NAME
-exim_db \- Exim's hint databases maintenance (exim_dumpdb, exim_fixdb, exim_tidydb)
+exim_db \- Exim's hint databases maintenance (exim_dumpdb, exim_fixdb, \
+exim_tidydb)
.SH SYNOPSIS
.B exim_dumpdb
.I spooldir database
@@ -28,7 +29,8 @@ exim_db \- Exim's hint databases mainten
.I spooldir database
.br
.B exim_tidydb
-.I [\-f] [\-t time] spooldir database
+.RB [ \-f "] [" \-t
+.IR time "] " "spooldir database"
.SH DESCRIPTION
Three utility programs are provided for maintaining the DBM files that
@@ -48,7 +50,7 @@ databases of information about messages
the callout cache
.TP
.B ratelimit
-the data for implementing the ratelimit ACL condition
+the data for implementing the ratelimit ACL condition
.TP
.B misc
other hints data (for example, for serializing ETRN runs)
@@ -72,9 +74,10 @@ It starts with one of the letters R, or
to a routing or transport retry.
For a local delivery, the next part is the local address; for a remote
delivery it is the name of the remote host, followed by its failing IP
-address (unless \(lqretry_include_ip_address\(rq is set false on the smtp
-transport). If the remote port is not the standard one (port 25), it is
-added to the IP address.
+address
+(unless \(lqretry_include_ip_address\(rq is set false on the smtp transport).
+If the remote port is not the standard one (port 25),
+it is added to the IP address.
Then there follows an error code, an additional error code, and a
textual description of the error.
@@ -101,9 +104,10 @@ utility program is used to tidy up the c
If run with no options, it removes all records that are more than 30 days
old. The age is calculated from the date and time that the record was last
updated. Note that, in the case of the retry database, it is not the time
-since the first delivery failure. Information about a host that has been
-down for more than 30 days will remain in the database, provided that the
-record is updated sufficiently often.
+since the first delivery failure.
+Information about a host that has been down for more than 30 days will
+remain in the database,
+provided that the record is updated sufficiently often.
The cutoff date can be altered by means of the \-t option, which must be
followed by a time.
@@ -117,8 +121,8 @@ Both the
and
.I retry
databases contain items that involve message ids.
-In the former these appear as data in records keyed by host - they were
-messages that were waiting for that host - and in the latter they are the
+In the former these appear as data in records keyed by host \(en they were
+messages that were waiting for that host \(en and in the latter they are the
keys for retry information for messages that have suffered certain types
of error.
When \(lqexim_tidydb\(rq is run, a check is made to ensure that message ids in
@@ -133,23 +137,31 @@ utility outputs comments on the standard
information from the database.
Certain records are automatically removed by Exim when they are no longer
-needed, but others are not. For example, if all the MX hosts for a domain
-are down, a retry record is created for each one. If the primary MX host
-comes back first, its record is removed when Exim successfully delivers to
-it, but the records for the others remain because Exim has not tried to use
-those hosts.
+needed,
+but others are not.
+For example,
+if all the MX hosts for a domain are down,
+a retry record is created for each one.
+If the primary MX host comes back first,
+its record is removed when Exim successfully delivers to it,
+but the records for the others remain because Exim has not tried to use
+those hosts.
-It is important, therefore, to run \(lqexim_tidydb\(rq periodically on all
-the hints databases. You should do this at a quiet time of day, because it
-requires a database to be locked (and therefore inaccessible to Exim) while
-it does its work. Removing records from a DBM file does not normally make
-the file smaller, but all the common DBM libraries are able to re-use the
-space that is released. After an initial phase of increasing in size, the
-databases normally reach a point at which they no longer get any bigger, as
-long as they are regularly tidied.
+It is important, therefore,
+to run \(lqexim_tidydb\(rq periodically on all the hints databases.
+You should do this at a quiet time of day,
+because it requires a database to be locked
+(and therefore inaccessible to Exim)
+while it does its work.
+Removing records from a DBM file does not normally make the file smaller,
+but all the common DBM libraries are able to re-use the space that is
+released.
+After an initial phase of increasing in size,
+the databases normally reach a point at which they no longer get any bigger,
+as long as they are regularly tidied.
Warning: If you never run \(lqexim_tidydb\(rq, the space used by the hints
-databases is likely to keep on increasing.
+databases is likely to keep on increasing.
The
.B exim_fixdb
@@ -179,9 +191,10 @@ hour, and minute.
Colons can be used as optional separators.
.SH BUGS
-This manual page needs a major re-work. If somebody knows better groff
-than us and has more experience in writing manual pages, any patches
-would be greatly appreciated.
+This manual page needs a major re-work.
+If somebody knows better groff than us and
+has more experience in writing manual pages,
+any patches would be greatly appreciated.
.SH SEE ALSO
.BR exim (8),
More information about the Pkg-exim4-maintainers
mailing list