Bug#1082620: exim4-config_files.5: Some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Mon Sep 23 13:06:50 BST 2024
Package: exim4-config
Version: 4.98-1
Severity: minor
Tags: patch
* 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>':409
troff:<stdin>:409: warning: [page 4, 6.6i]: cannot break 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.10.9-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-config depends on:
ii adduser 3.137
ii debconf [debconf-2.0] 1.5.87
Versions of packages exim4-config recommends:
ii ca-certificates 20240203
exim4-config suggests no packages.
-- Configuration Files:
/etc/exim4/passwd.client [Errno 13] Permission denied: '/etc/exim4/passwd.client'
-- debconf information excluded
-------------- next part --------------
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <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 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 -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint exim4-config_files.5": (possibly shortened list)
mandoc: exim4-config_files.5:5:26: STYLE: normalizing date format to: TH January 4, 2015
mandoc: exim4-config_files.5:23:2: WARNING: skipping paragraph macro: br after SH
mandoc: exim4-config_files.5:82:2: WARNING: skipping paragraph macro: br after PP
mandoc: exim4-config_files.5:93:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:114:2: WARNING: skipping paragraph macro: br after PP
mandoc: exim4-config_files.5:128:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:135:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:155:2: WARNING: skipping paragraph macro: br after PP
mandoc: exim4-config_files.5:169:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:176:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:183:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:191:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:201:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:216:2: WARNING: skipping paragraph macro: br after PP
mandoc: exim4-config_files.5:234:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:243:2: WARNING: skipping paragraph macro: br after PP
mandoc: exim4-config_files.5:261:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:270:2: WARNING: skipping paragraph macro: br after PP
mandoc: exim4-config_files.5:316:2: WARNING: skipping paragraph macro: br after PP
mandoc: exim4-config_files.5:340:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:347:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:354:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:359:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:368:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:372:2: WARNING: skipping paragraph macro: PP after SS
mandoc: exim4-config_files.5:411:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:413:2: WARNING: skipping paragraph macro: br after SH
mandoc: exim4-config_files.5:423:2: WARNING: skipping paragraph macro: PP empty
mandoc: exim4-config_files.5:427:2: WARNING: skipping paragraph macro: PP empty
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
337:^smtp[0\-9]*\\.mail\\.server\\.example:user:password
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
394:is equivalent to an empty one. - Exim tries to match the IP-address of the
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URLs (web address)
409 <http://www.exim.org/exim\-html\-current/doc/html/spec_html/ch\-domain_host_address_and_local_part_lists.html>
-.-.
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.
377:e.g. if resolving a
388:does not match the list. e.g. a local_host_blacklist consisting of
-.-.
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.
59:recipients. /etc/aliases is a text file which is roughly compatible
60:with Sendmail. The file should contain lines of the form
64:The name is a local address without domain part. All local domains are
65:handled equally. For more detailed documentation, please refer to
67:/usr/share/doc/exim4\-base/README.Debian.gz. Please note that it
69:pipes. This is forbidden in Debian's exim4 default configuration.
75:is used to rewrite the email addresses of users. This is particularly
89:the outside world. Technically, the from, reply\-to, and sender
98:"locally blacklisted". This is a full exim 4 host list, and all
99:available features can be used. This includes negative items, and so
100:it is possible to exclude addresses from being blacklisted. For
103:/etc/exim4/host_local_deny_exceptions. Entries in the whitelist override
141:used. This includes negative items, and so it is possible to exclude
142:addresses from being blacklisted. For convenience, as an additional
144:whitelist is read in from /etc/exim4/sender_local_deny_exceptions. Entries
180:messages are subject to sender verification with a callout. This is a
188:callout. This is a full exim4 address list, and all available features
195:messages are exempt from blacklisting via a domain-based DNSBL. This
205:be used to override or augment MX information from the DNS. This is
247:crypted-password is the crypt(3)-created hash of your password. You
249:create a crypted password. It is recommended to use a modern hash
250:algorithm, see mkpasswd \-\-method=help. Consider not using crypt or MD5.
254:authentication. If you don't plan on doing so, the third column can be
259:readable for others. Recommended file mode is root:Debian\-exim 640.
307:password is your SMTP password in clear text. If you do not know about
313:readable for others. Recommended file mode is root:Debian\-exim 640.
356:The "mail name" of the system. See Debian policy Chapter Customized programs
361:Plenty. Please report them through the Debian BTS
364:This manual page needs a major re-work. If somebody knows better groff
377:e.g. if resolving a
388:does not match the list. e.g. a local_host_blacklist consisting of
394:is equivalent to an empty one. - Exim tries to match the IP-address of the
396:fails, exim behaves as if the connecting host does not match the list. List
-.-.
Use \(en (en-dash) for a dash between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
exim4-config_files.5:394:is equivalent to an empty one. - Exim tries to match the IP-address of the
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':409
troff:<stdin>:409: warning: [page 4, 6.6i]: cannot break line
-------------- next part --------------
--- exim4-config_files.5 2024-09-23 11:32:59.585585522 +0000
+++ exim4-config_files.5.new 2024-09-23 11:58:15.524758917 +0000
@@ -18,9 +18,8 @@
.\" \(oqthis text is enclosed in single quotes\(cq
.\" \(lqthis text is enclosed in double quotes\(rq
.SH NAME
-exim4-config_files \- Files in use by the Debian exim4 packages
+exim4\-config_files \- Files in use by the Debian exim4 packages
.SH SYNOPSIS
-.br
/etc/aliases
.br
/etc/email\-addresses
@@ -79,7 +78,6 @@ useful for users who use their ISP's dom
The file should contain lines of the form
.
.LP
-.br
user: someone at isp.com
.br
otheruser: someoneelse at anotherisp.com
@@ -90,7 +88,6 @@ the outside world. Technically, the from
addresses, along with the envelope sender, are rewritten for users that
appear to be in the local domain.
.
-.LP
.SH /etc/exim4/local_host_blacklist
.I [exim host list]
is an optional file containing a list of IP addresses, networks and
@@ -111,7 +108,6 @@ follows a positive item, and as "and" if
For example, a /etc/exim4/local_host_blacklist
.
.LP
-.br
192.168.10.0/24
.br
!172.16.10.128/26
@@ -125,14 +121,12 @@ Exim just evaluates left to right (or up
context), so you don't get the same kind of operator binding as in a
programming language.
.
-.LP
.SH /etc/exim4/host_local_deny_exceptions
.I [exim host list]
contains a list of IP addresses, networks and host names whose
messages will be accepted despite the address is also listed in
/etc/exim4/local_host_blacklist, overriding a blacklisting.
.
-.LP
.SH /etc/exim4/local_sender_blacklist
.I [exim address list]
is an optional files containing a list of envelope senders whose
@@ -152,7 +146,6 @@ follows a positive item, and as "and" if
For example, a /etc/exim4/local_sender_blacklist
.
.LP
-.br
domain1.example
.br
!local at domain2.example
@@ -166,21 +159,18 @@ Exim just evaluates left to right (or up
context), so you don't get the same kind of operator binding as in a
programming language.
.
-.LP
.SH /etc/exim4/sender_local_deny_exceptions
.I [exim address list]
is an optional file containing a list of envelope senders whose messages
will be accepted despite the address being also listed in
/etc/exim4/local_sender_blacklist, overriding a blacklisting.
.
-.LP
.SH /etc/exim4/local_sender_callout
.I [exim address list]
is an optional file containing a list of envelope senders whose
messages are subject to sender verification with a callout. This is a
full exim4 address list, and all available features can be used.
.
-.LP
.SH /etc/exim4/local_rcpt_callout
.I [exim address list]
is an optional file containing a list of envelope recipients for which
@@ -188,7 +178,6 @@ incoming messages are subject to recipie
callout. This is a full exim4 address list, and all available features
can be used.
.
-.LP
.SH /etc/exim4/local_domain_dnsbl_whitelist
.I [exim address list]
is an optional file containing a list of envelope senders whose
@@ -198,7 +187,6 @@ This feature is intended to be used in c
being too heavy handed, for example listing entire top-level domains
for their registry policies.
.
-.LP
.SH /etc/exim4/hubbed_hosts
.I [exim domain list]
is an optional file containing a list of route_data records which can
@@ -213,7 +201,6 @@ The file should contain key-value pairs
data of the form
.
.LP
-.br
domain: host-list options
.br
dict.ref.example: mail\-1.ref.example:mail\-2.ref.example
@@ -231,7 +218,6 @@ mail to bar.example to be sent to 192.16
See spec.txt chapter 20.3 through 20.7 for a more detailed explanation
of host list format and available options.
.
-.LP
.SH /etc/exim4/passwd
contains account and password data for SMTP authentication when the
local exim is SMTP server and clients authenticate to the local exim.
@@ -240,7 +226,6 @@ local exim is SMTP server and clients au
The file should contain lines of the form
.
.LP
-.br
username:crypted-password:clear-password
.
.LP
@@ -258,7 +243,6 @@ omitted completely.
This file must be readable for the Debian\-exim user and should not be
readable for others. Recommended file mode is root:Debian\-exim 640.
.
-.LP
.SH /etc/exim4/passwd.client
contains account and password data for SMTP authentication when exim
is authenticating as a client to some remote server.
@@ -267,7 +251,6 @@ is authenticating as a client to some re
The file should contain lines of the form
.
.LP
-.br
target.mail.server.example:login-user-name:password
.
.LP
@@ -313,7 +296,6 @@ This file must be readable for the Debia
readable for others. Recommended file mode is root:Debian\-exim 640.
.
.LP
-.br
# example for CONFDIR/passwd.client
.br
# this will only match if the server's generic name matches exactly
@@ -334,29 +316,25 @@ mail.server.example:user:password
.br
# the regular expression
.br
-^smtp[0\-9]*\\.mail\\.server\\.example:user:password
+^smtp[0\-9]*\e.mail\e.server\e.example:user:password
.br
.
-.LP
.SH /etc/exim4/exim.crt
contains the certificate that exim uses to initiate TLS connections.
This is public information and can be world readable.
/usr/share/doc/exim4\-base/examples/exim\-gencert can
be used to generate a private key and self-signed certificate.
.
-.LP
.SH /etc/exim4/exim.key
contains the private key belonging to the certificate in exim.crt.
This file's contents must be kept secret and should have mode
root:Debian\-exim 640. /usr/share/doc/exim4\-base/examples/exim\-gencert
can be used to generate a private key and self-signed certificate.
.
-.LP
.SH /etc/mailname
The "mail name" of the system. See Debian policy Chapter Customized programs
and exim4-base's README.Debian for further details.
.
-.LP
.SH BUGS
Plenty. Please report them through the Debian BTS
.
@@ -365,16 +343,14 @@ This manual page needs a major re-work.
than us and has more experience in writing manual pages, any patches
would be greatly appreciated.
.
-.LP
.SH NOTES
.SS Unresolvable items in host lists
.
-.LP
Adding or keeping items in the abovementioned host lists which are not
resolvable by DNS has severe consequences.
.
.LP
-e.g. if resolving a
+e.g., if resolving a
.B hostname
in local_host_blacklist returns a temporary error (DNS timeout) exim
will not be able to check whether a connecting host is part of the list.
@@ -385,13 +361,13 @@ connecting host.
.LP
On the other hand if there is a permanent error in resolving a name in the
host list (the record was removed from DNS) exim behaves as if the host
-does not match the list. e.g. a local_host_blacklist consisting of
+does not match the list. e.g., a local_host_blacklist consisting of
.
.LP
notresolvable.example.com:rejectme.example.com
.
.LP
-is equivalent to an empty one. - Exim tries to match the IP-address of the
+is equivalent to an empty one. \(en Exim tries to match the IP-address of the
connecting host to notresolvable.example.com, resolving this IP by DNS
fails, exim behaves as if the connecting host does not match the list. List
processing stops at this point!
@@ -406,11 +382,9 @@ See Exim specification Chapter
.I Domain, host, address, and local part lists
, section
.I Behaviour when an IP address or name cannot be found.
-<http://www.exim.org/exim\-html\-current/doc/html/spec_html/ch\-domain_host_address_and_local_part_lists.html>
+<http://www.exim.org/exim\-html\-current/\:doc/\:html/\:spec_html/\:ch\-domain_host_address_and_local_part_lists.html>
.
-.LP
.SH SEE ALSO
-.br
.BR exim (8),
.br
.BR update\-exim4.conf (8),
@@ -420,8 +394,6 @@ See Exim specification Chapter
and for general notes and details about interaction with debconf
.B /usr/share/doc/exim4\-base/README.Debian.gz
.
-.LP
.SH AUTHOR
Marc Haber <mh+debian-packages at zugschlus.de> with help from Ross Boylan.
.
-.LP
More information about the Pkg-exim4-maintainers
mailing list