Bug#650137: Package description - wrong focus in standard boilerplate?

[Justin B Rye]

Martin Eberhard Schauer wrote:
> What I remember from a glimpse to the "Developer's reference" is the demand to
> give the person having a look at the description some rationale whether to
> install the package or not. The fourth paragraph of (1) has lots of Debian
> specific information. IMHO the most important sentence there is "Please ...
> only write to the upstream exim-users mailing list if you are sure that your
> question is not Debian-specific."
> 
> I suggest to shorten this paragraph and to give more information on Exim,
> perhaps by borrowing from upstream (2):
> 
>   Exim is a message transfer agent (MTA) ... . In style it is similar to Smail
>   3, but its facilities are more general. There is a great deal of flexibility
>   in the way mail can be routed, and there are extensive facilities for
>   checking incoming mail. Exim can be installed in place of Sendmail, although
>   the configuration of Exim is quite different.

This looks like a bad source to copy from, given that it obviously
hasn't been updated since Exim overtook Smail a decade or more ago.
Smail's homepage offers a version 3.2, a warning that anything less
than the upcoming version 3.3 is dangerously insecure on GNU/Linux,
and a last-updated timestamp in 2006.
 
> Furthermore I have the impression that Exim is an important part of the Debian
> infrastructure. It's on my system and I'm quite shure not to have installed it
> separately.

That would probably be because cron among other packages Recommends: a
mail-transport-agent (so that cronjob output can reach its intended
destination), and exim4 is the default MTA in Debian.  I gather there
is intermittent debate about whether it's still appropriate for Debian
to prefer a "heavyweight" mailserver like Exim rather than some
minimalist SMTP server that's limited to punting everything in the
general direction of gmail.com, but for now exim4 is what you get on a
default Debian install.
 
> My thougths on the content of some revised standard boilerplate:
> 
>   Exim is a message transfer agent (MTA), similar in style to Smail
>   3, but with more general facilities. There is a great deal of flexibility
>   in the way mail can be routed, and there are extensive facilities for
>   checking incoming mail. It can replace Sendmail, but the configuration of
>   Exim is quite different.

The middle sentence might be an improvement on the current package
description, but the comparisons with Smail and even Sendmail are
fairly pointless.  Debian users won't be using Exim to "replace
Sendmail", since they could only ever have got Sendmail installed in
the first place if they'd actively chosen it.

And even if this was a good description of Exim 4, it wouldn't be an
adequate description of the package exim4, which needs to mention the
fact it's a dependency metapackage.
 
>   Exim is a vital component of a standard Debian system, as it is used for
> <... something I did find out yet>.
> 
>   There is a lot of Debian specific infrastructure: <perhaps some links>.
>   Please only write to the upstream exim-users mailing list if you are sure
>   that your question is not Debian-specific.

I would agree that the huge pileup of information sources in that
paragraph is a bad idea (unless the idea is to bury things so that the
maintainers can shout at users for not having noticed them).  Is it so
difficult to arrange for each of those locations to point at a single
authoritative source that either has all the information or at least
all the signposts?  I mean, the list mentions that there's an FAQ, but
not where it is; couldn't you just give the URL, and have the first
entry in it warn against taking Debian bugs upstream?

My own tentative suggestion for the whole thing would be something
along these lines:

 Description: flexible mail transport agent - metapackage
  Exim (v4) is a mail transport agent with a great deal of flexibility
  in the way mail can be routed, and extensive facilities for checking
  incoming mail. Comprehensive upstream documentation is supplied in
  /usr/share/doc/exim4-base/spec.txt.gz, but many configuration details
  are Debian-specific, so before reporting a bug, read
  http://wiki.debian.org/PkgExim4UserFAQ
  .
  This metapackage depends on the essential components for a basic
  installation of Exim 4.

(I say "comprehensive" to avoid repeating "extensive".)  Then for
instance exim4-base could be:

 Description: $SUITE - support files
  $BOILERPLATE
  .
  This package provides support files needed by all Exim 4 daemon
  packages (exim4-daemon-light, exim4-daemon-heavy, or an
  exim4-daemon-custom package locally built from source).

And exim4-daemon-light would be something like:

 Description: $SUITE - lightweight flavor
  $BOILERPLATE
  .
  This package provides a version of the Exim 4 daemon with only basic
  features enabled. It works well with the standard setups that are
  provided by Debian and includes support for TLS encryption and the
  dlopen patch to allow dynamic loading of a local_scan function.

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package