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

[Marc Haber]

On Thu, Jun 08, 2006 at 03:16:22PM -0700, Ross Boylan wrote:
> 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

Stupid me. Fixed.

> ? (not sure you need the "valid").

the "valid" is a reminder for myself that the issue has already been
checked.

> > 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?

Yes.

> That seems
> reasonable, as long as README.Debian has an appropriate pointer.

I'll probably include a list of man pages in the README file. Today's
user are not aware of apropos any more.

> > 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?

That's what I meant.

> > 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.

Actually, it is the goal to have README.Debian relevant for everybody,
and the information in the actual configuration files for the people
who intend to change the config themselved.

> 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.

README.Debian is getting too long. Man pages are a good thing.

> 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)

The exim4 man page comes from upstream. I am reluctant to change it.

> 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.

Probably. A list like this is prone to be desynced though. grep is a
good tool.

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