Bug#369126: exim4-config: Consider a bit more documentation for /etc/email-addresses (and others?)

[Marc Haber]

retitle #369126 multiple valid configuration issues
tags #369126 confirmed
thanks

Hi Ross,

I really appreciate your persistence. Your points are mostly valid.

On Thu, Jun 08, 2006 at 01:28:33PM -0700, Ross Boylan wrote:
> > > A man page would be a nice touch too, if you don't consider it overkill.
> > 
> > > The use and syntax of the file are well documented in the file itself; the
> > > problem is knowing that the file is there.
> > [...]
> > 
> > If knowing that the file is there is the issue a manpage won't help
> > all, will it?
> 
> Well, knowing that the file is there isn't the only issue.  Currently, the
> changelog/news files refer to email-addresses without details, and the 
> README just indicates one purpose the file might serve, without specifics.
> 
> FYI I looked for the man page because I saw a reference to the file in
> the changelog or news (don't remember which), and thought it, like
> mailname, was a Debian-wide file.
> 
> Possible language:
> --------------------------------------------------------------------
> /etc/email-addresses
> --------------------
> 
> Use this optional file to rewrite the email addresses of users.  This
> is particularly useful for [dialup? not sure that matters] users who
> don't have their own domain.
> 
> [or maybe "particularly useful if you use your ISP's domain for email."]
> 
> [I struggled with "users", "local users", and "users in the local
> domain".  The last is technically accurate, but probably mystifying to many.
> "local users" is friendly, but inaccurate, since it means "users have a local account."
> I went with "users" and offered the details in the final paragraph.]
> 
> The file should contain lines of the form:
> 
> user: someone at isp.com
> otheruser: someoneelse at anotherisp.com
> 
> This way emails from user will appear to be from someone at isp.com to the outside
> world.  Technically, the from, reply-to, and sender addresses, along with the
> envelope sender, are rewritten for users that appear to be in the local domain.
> [I keep wanting the cc included too, but that's a separate issue :)]
> ----------------------------------------------------------------------

That's a really good starting point.

> This might go after the current section 2.1.2, in a new
> 2.1.3 Using Exim Files to control configuration
> with later sections bumped up one.

How about having a man page exim4_files(5) which would be symlinked to
the actual file names? This strikes me like the natural point where
one might look for the documentation.

Having one man page per file is clearly overkill and I am too lazy to
maintain them, but having one man page for all the files seems
acceptable.

> Poking around, I see local_sender_callout, local_rcpt_callout,
> local_domain_dnsbl_whitelist, hubbed_hosts, and a bunch of
> security/authentication files.  Perhaps they should be mentioned
> somewhere (if I haven't missed it--passwd.client is mentioned).

Yes, these files should be in the man page. I'll look around for them
and document them. Then I'd like you to check whether I missed any.

> There are 4 black/whitelist files that are described in
> /usr/share/doc/exim4-config/default_acl.
>Perhaps mention default_acl
> in the main README.Debian (e.g., in my new 2.1.3).

I totally missed that file. I'll incorporate this into the main
README.Debian.

> Also, the main exim
> manpage has no Files section.

That cannot be easily fixed since the exim man page is automatically
generated upstream and I'd like to keep patches applied to that man
page minimal.

I'd be willing to add a SEE ALSO section refering to README.Debian.

Your issues require more work than I can do right away, I'm retitling
and retagging this bug appropriately for later work on it.

Greetings
Marc

-- 
-----------------------------------------------------------------------------
Marc Haber         | "I don't trust Computers. They | Mailadresse im Header
Mannheim, Germany  |  lose things."    Winona Ryder | Fon: *49 621 72739834
Nordisch by Nature |  How to make an American Quilt | Fax: *49 621 72739835