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: [EMAIL PROTECTED] > > otheruser: [EMAIL PROTECTED] > > > > This way emails from user will appear to be from [EMAIL PROTECTED] 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 [EMAIL PROTECTED] Dept of Epidemiology and Biostatistics fax: (415) 514-8150 University of California, San Francisco San Francisco, CA 94107-1739 hm: (415) 550-1062 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
