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

[Ross Boylan]

On Thu, 2006-06-08 at 23:28 +0200, Marc Haber wrote:
> retitle #369126 multiple valid configuration issues
> tags #369126 confirmed
> thanks
> 
The new title might be a bit misleading; maybe
multiple valid configuration documentation issues
? (not sure you need the "valid").

> Hi Ross,
> 
> I really appreciate your persistence. Your points are mostly valid.
I have my moments :)
> 
> 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 meant "users having 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.

By symlinked to the actual file names you mean symlinks for the man
pages, so man email-addresses gets you this master page?  That seems
reasonable, as long as README.Debian has an appropriate pointer.
> 
> 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.
OK.  I basically did a search on CONFDIR/ in exim4.conf.template.  Which
means I might have missed some stuff.
> 
> > 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.

Or perhaps just incorporate the text into README.Debian?  Or did you
mean that?

> 
> > 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.
That sounds OK.
> 
> Your issues require more work than I can do right away, I'm retitling
> and retagging this bug appropriately for later work on it.

Terrific.  My one concern here is that info on Debian customization is
getting spread out in quite a few places (README.Debian, man
update-exim4.conf, default_acl, the bodies of the files under conf.d,
debconf questions, maybe some others, maybe a new page on files) and
that could become a barrier to understanding.  One thing these all have
in common is that they are only for the exim4-config.

Perhaps consolidating would be good.  README.Debian and the
update-exim4.conf man page are two natural candidates.  Some kind of
package-specific man page (exim4_conf?) might be another.

The exim4 man page itself is another spot.  I'm not sure if making a
little change or a big change to that page is so different, but I'll
just mention some of the +'s and -'s I see with that route:
+ the standard place to look for documentation
+ one stop shopping for users
+ has a framework that fits some of this (e.g., a files section)

- there would need to be one man page if exim4-conf is installed, and
another (vanilla) one otherwise
- the already huge man page would get bigger
- the man page and the other forms of documentation (the info file,
upstream man page) would diverge
- people might not think to look there for Debian customizations,
particularly since customization would probably be toward the end
- for people who already know exim, it may be more natural to have
Debian-specific issues discussed separately.

An easier route might be just to list the files, with perhaps a one line
description and a reference to the config snippet in which they are
used.  The main docs would then remain in the comments of the config
snippets.

Thanks for your work on the package.  Thanks to Andreas too.  I'm glad
to help make it better, and I agree that the changes can wait.
-- 
Ross Boylan                                      wk:  (415) 514-8146
185 Berry St #5700                               ross at biostat.ucsf.edu
Dept of Epidemiology and Biostatistics           fax: (415) 514-8150
University of California, San Francisco
San Francisco, CA 94107-1739                     hm:  (415) 550-1062