Bug#486855: apache2: outdated package descriptions
Package: apache2
Version: 2.2.9-1
Severity: minor
Tags: patch
Apache 2 is the only version of Apache currently in Debian, so it's
time its package descriptions took responsibility for describing
what it is, instead of saying what it's better than.
Here's a review of the current control file, with suggestions for
package-description improvements throughout. Patch attached, though
I'd be surprised if this draft was good enough.
# Source: apache2
# Section: web
# Priority: optional
# Maintainer: Debian Apache Maintainers <debian-apache@lists.debian.org>
# Uploaders: Tollef Fog Heen <tfheen@debian.org>, Thom May <thom@debian.org>, Adam Conrad <adconrad@0c3.net>, Peter Samuelson <peter@p12n.org>, Stefan Fritsch <sf@debian.org>
# Build-Depends: debhelper (>=4.1.16), dpatch, lsb-release, libaprutil1-dev, libapr1-dev (>= 1.2.7-6), openssl, libpcre3-dev, libtool, mawk, zlib1g-dev, libssl-dev, sharutils
# Standards-Version: 3.7.3.0
# XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-apache/trunk/apache2
# XS-Vcs-svn: svn://svn.debian.org/pkg-apache/trunk/apache2
# Homepage: http://httpd.apache.org/
#
# Package: apache2.2-common
# Architecture: any
# Depends: ${shlibs:Depends}, ${misc:Depends}, apache2-utils, net-tools, libmagic1, mime-support, lsb-base, procps [!hurd-i386]
# Suggests: www-browser, apache2-doc
# Conflicts: apache2-common, libapache2-mod-php5 (<= 5.1.6-3), libapache2-mod-php4 (<= 4:4.4.4-2), libapache2-mod-mime-xattr (<= 0.3-2), libapache2-mod-mono (<= 1.1.17-3), libapache2-mod-proxy-html (<= 2.4.3-2), libapache2-mod-scgi (<= 1.11-1), libapache2-mod-speedycgi (<= 2.22-3), libapache2-modxslt (<= 2005072700-1), libapache2-redirtoservername (<= 0.1-1), libapache2-webauth (<= 3.5.3-1), libapache2-webkdc (<= 3.5.3-1)
# Replaces: apache2-common
# Description: Next generation, scalable, extendable web server
When I'm reading software descriptions my usual rule of thumb is
that "The Next Generation" means "old hat ten years ago". It's not
quite that bad in this case, but given that the previous generation
was pensioned off to legacy-support years ago, it's about time the
phrase came out of this line.
The word "extendable" is recognised by most dictionaries, but the
form that's usually preferred (and used in apache.org blurbs) is
"extensible".
However, this package synopsis is identical to the one for apache2
(the MPM metapackage)! It would make more sense to leave the
advertising copy out of the short description and concentrate on
identifying the package in terms of how it fits into the suite.
Something like:
Description: Apache HTTP Server common files
"Apache" is just what it's known as for short; officially Apache is
the overarching development project, and this is their HTTP Server.
This seems the neatest way of combining that with a uniform synopsis
style.
# Apache v2 is the next generation of the omnipresent Apache web server. This
# version - a total rewrite - introduces many new improvements, such as
# threading, a new API, IPv6 support, request/response filtering, and more.
# .
# It is also considerably faster, and can be easily extended to provide services
# other than http.
Stop telling me what it's better than! I don't have the option of
apt-get installing apache1, so this needs to be rephrased in terms
of "absolute" rather than "relative" features.
Moving the advertising from the short description and bulking it out
with more of the apache.org blurbage in the same vein, I'd suggest:
The Apache Software Foundation's goal is to build a secure, efficient and
extensible HTTP server as standards-compliant open source software. The
result has long been the number one web server on the Internet.
(Improvements welcome.) Plus maybe some lists of features, but they
really belong in the long description for the apache2 metapackage
rather than here. This paragraph can stay:
# This package contains all the standard apache2 modules, including SSL support.
# However, it does *not* include the server itself; for this you need to
# install one of the apache2-mpm-* packages; such as worker or prefork.
Except that last semicolon should be at most a comma.
# Package: apache2-mpm-worker
# Architecture: any
# Depends: ${shlibs:Depends}, apache2.2-common (= ${binary:Version})
# Provides: apache2-mpm, apache2, httpd, httpd-cgi
# Conflicts: apache2-mpm, apache2-common
# Replaces: apache2-mpm-threadpool (<< 2.0.53), apache2-mpm-perchild (<< 2.2.0)
# Description: High speed threaded model for Apache HTTPD
# The worker MPM provides a threaded implementation for Apache HTTPD. It is
# considerably faster than the traditional model, and is the recommended MPM.
# .
# Worker generally is a good choice for high-traffic servers because it
# has a smaller memory footprint than the prefork MPM.
The problem here is that "MPM" is Apache-specific jargon. Not that
knowing the expansion helps much, since the reference to modules
just makes it sound as if the /usr/sbin/apache2 binary can load and
unload mod_worker.so or mod_prefork.so as optional extras. Instead
they're compiled-in alternative "engines".
This package should also mention that -worker is the flavour you'll
get automatically with a standard Debian apache2 install (especially
since the upstream docs seem to say it's prefork).
All the MPM descriptions should start with a standard what-an-MPM-is
text, and then say what's so special about this one - something like
this:
Description: Apache HTTP Server - high speed threaded model
Each Apache Multi-Processing Module provides a different "flavor" of
web server binary, compiled with a different processing model.
.
The worker MPM provides the default threaded implementation. It is
recommended especially for high-traffic sites because it is faster
and has a smaller memory footprint than the traditional prefork MPM.
# Package: apache2-mpm-prefork
# Architecture: any
# Depends: ${shlibs:Depends}, apache2.2-common (= ${binary:Version})
# Provides: apache2-mpm, apache2, httpd, httpd-cgi
# Conflicts: apache2-mpm, apache2-common
# Description: Traditional model for Apache HTTPD
# This Multi-Processing Module (MPM) implements a non-threaded,
# pre-forking web server that handles requests in a manner similar to
# Apache 1.3. It is appropriate for sites that need to avoid threading for
# compatibility with non-thread-safe libraries. It is also the best MPM
# for isolating each request, so that a problem with a single request will
# not affect any other.
# .
# It is not as fast, but is considered to be more stable.
Description: Apache HTTP Server - traditional non-threaded model
Each Apache Multi-Processing Module provides a different "flavor" of
web server binary, compiled with a different processing model.
.
The prefork MPM provides a non-threaded, pre-forking implementation
that handles requests in a manner similar to Apache 1.3. It is not as
fast as threaded models, but is considered to be more stable. It is
appropriate for sites that need to maintain compatibility with
non-thread-safe libraries, and is the best MPM for isolating each
request, so that a problem with a single request will not affect any
other.
# Package: apache2-mpm-event
# Architecture: any
# Depends: ${shlibs:Depends}, apache2.2-common (= ${binary:Version})
# Provides: apache2-mpm, apache2, httpd, httpd-cgi
# Conflicts: apache2-mpm, apache2-common
# Description: Event driven model for Apache HTTPD
# The event Multi-Processing Module (MPM) is designed to allow more
# requests to be served simultaneously by passing off some processing
# work to supporting threads, freeing up the main threads to work on
# new requests.
# .
# This MPM is especially suitable for sites that see extensive KeepAlive traffic
Description: Apache HTTP Server - event driven model
Each Apache Multi-Processing Module provides a different "flavor" of
web server binary, compiled with a different processing model.
.
The event MPM is designed to allow more requests to be served
simultaneously by passing off some processing work to supporting
threads, freeing up the main threads to work on new requests. It is
especially suitable for sites that see extensive KeepAlive traffic.
# Package: apache2-mpm-perchild
# Architecture: all
# Depends: apache2-mpm-worker
# Description: Transitional package - please remove
# This is a transitional package to upgrade apache2-mpm-perchild to
# apache2-mpm-worker.
Is this getting retired after the Lenny release? It was already a
transitional package in Etch.
# Package: apache2-utils
# Architecture: any
# Replaces: apache2-common, apache-utils (<< 1.3.33-4)
# Conflicts: apache-common (<< 1.3.28.0.1-1)
# Depends: ${shlibs:Depends}
# Description: utility programs for webservers
# Provides some add-on programs useful for any webserver. These include:
# - ab (Apache benchmark tool)
# - logresolve (Resolve IP addresses to hostname in logfiles)
# - htpasswd (Manipulate basic authentication files)
# - htdigest (Manipulate digest authentication files)
# - dbmmanage (Manipulate basic authentication files in DBM format, using perl)
# - htdbm (Manipulate basic authentication files in DBM format, using APR)
# - rotatelogs (Periodically stop writing to a logfile and open a new one)
# - split-logfile (Split a single log including multiple vhosts)
# - checkgid (Checks whether the caller can setgid to the specified group)
# - check_forensic (Extract mod_log_forensic output from apache log files)
One or two formatting quibbles (such as s/perl/Perl/), but never
mind.
# Package: apache2
# Architecture: all
# Depends: apache2-mpm-worker (>= ${source:Version}) | apache2-mpm-prefork (>= ${source:Version}) | apache2-mpm-event (>= ${source:Version})
# Section: web
# Description: Next generation, scalable, extendable web server
# Apache v2 is the next generation of the omnipresent Apache web server. This
# version - a total rewrite - introduces many new improvements, such as
# threading, a new API, IPv6 support, request/response filtering, and more.
This is where the main writeup for Apache should be. I'll replace
the synopsis with one intended to make it clearer that this is an
empty dependency package that just guarantees the installation of
some /usr/sbin/apache2 flavour out of the main Apache tree:
Description: Apache HTTP Server metapackage
The Apache Software Foundation's goal is to build a secure, efficient and
extensible HTTP server as standards-compliant open source software. The
result has long been the number one web server on the Internet.
Unfortunately I don't really know enough about what features people
would be looking for in a state-of-the-art webserver these days, so
the following is a bit lame (largely stolen from Wikipedia):
.
It features support for HTTPS, virtual hosting, CGI and FastCGI, SSI,
IPv6, easy scripting and database integration, request/response
filtering, many flexible authentication schemes, and more.
Improvements to that paragraph would be particularly welcome.
# Package: apache2-doc
# Section: doc
# Architecture: all
# Description: documentation for apache2
# This is the documentation for apache2, see the apache2 package description
# for more details.
It's more traditional to have a bit of boilerplate description here,
but I suppose this is fine. Apart from being repetitive and a comma
splice, that is. Make it:
Description: Apache HTTP Server documentation
This package provides the documentation for Apache 2. For more details
see the apache2 package description.
Note that at present most of those "details" (such as they are) live
in the apache2.2-common package description, not the apache2 package
description. Which sounds like a vote in favour of the way I've
moved them.
# Package: apache2-prefork-dev
# Section: devel
# Architecture: any
# Depends: apache2.2-common (= ${binary:Version}), openssl, libaprutil1-dev
# Conflicts: apache2-threaded-dev
# Priority: extra
# Description: development headers for apache2
Since this and apache2-threaded-dev have duplicate synopses, I'd
suggest changing it to:
Description: Apache development headers - non-threaded MPM
# This package provides the development headers and apxs2 binary for
# apache2-mpm-prefork; see the apache2 package description for more details.
Another vote for moving the main blurb - or is this pointing at the
detailed explanation for MPMs, which isn't there either?
# .
# This should only be used when you absolutely *have* to have a non-threaded
# environment, ie for PHP4.
If you really mean "i.e." here you might as well say directly that
"This should *only* be used for PHP4". However, I suspect you mean
"e.g.", not "i.e."; so avoid this confusion by using English.
This should only be used when you absolutely *must* support a non-threaded
environment (for PHP4, for example).
# Package: apache2-threaded-dev
# Section: devel
# Architecture: any
# Depends: apache2.2-common (= ${binary:Version}), openssl, libaprutil1-dev
# Conflicts: apache2-prefork-dev
# Provides: apache2-dev
# Priority: extra
# Description: development headers for apache2
Duplicate package synopsis (see above):
Description: Apache development headers - threaded MPM
# This package provides the development headers and apxs2 binary for
# threaded versions of apache2; see the apache2 package description
# for more details.
Another vote.
# Package: apache2-src
# Section: devel
# Priority: extra
# Architecture: all
# Description: Apache source code
# This package includes the complete and patched source code for the
# Apache HTTPD. It is useful for other packages to build-depend on in
# order to build custom MPMs.
#
# Package: apache2-dbg
# Section: libdevel
# Priority: extra
# Architecture: any
# Depends: apache2.2-common (= ${binary:Version})
# Description: Apache debugging symbols
# This package includes the debugging symbols for Apache 2.
These don't need changing.
-- System Information:
Debian Release: lenny/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: i386 (i686)
Kernel: Linux 2.6.25.custom
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
-- no debconf information
--
JBR
Ankh kak! (Ancient Egyptian blessing)
diff -ru apache2-2.2.8.pristine/debian/control apache2-2.2.8/debian/control
--- apache2-2.2.8.pristine/debian/control 2008-06-16 11:47:23.000000000 +0100
+++ apache2-2.2.8/debian/control 2008-06-18 13:28:24.000000000 +0100
@@ -15,17 +15,14 @@
Suggests: www-browser, apache2-doc
Conflicts: apache2-common, libapache2-mod-php5 (<= 5.1.6-3), libapache2-mod-php4 (<= 4:4.4.4-2), libapache2-mod-mime-xattr (<= 0.3-2), libapache2-mod-mono (<= 1.1.17-3), libapache2-mod-proxy-html (<= 2.4.3-2), libapache2-mod-scgi (<= 1.11-1), libapache2-mod-speedycgi (<= 2.22-3), libapache2-modxslt (<= 2005072700-1), libapache2-redirtoservername (<= 0.1-1), libapache2-webauth (<= 3.5.3-1), libapache2-webkdc (<= 3.5.3-1)
Replaces: apache2-common
-Description: Next generation, scalable, extendable web server
- Apache v2 is the next generation of the omnipresent Apache web server. This
- version - a total rewrite - introduces many new improvements, such as
- threading, a new API, IPv6 support, request/response filtering, and more.
- .
- It is also considerably faster, and can be easily extended to provide services
- other than http.
+Description: Apache HTTP Server common files
+ The Apache Software Foundation's goal is to build a secure, efficient and
+ extensible HTTP server as standards-compliant open source software. The
+ result has long been the number one web server on the Internet.
.
This package contains all the standard apache2 modules, including SSL support.
However, it does *not* include the server itself; for this you need to
- install one of the apache2-mpm-* packages; such as worker or prefork.
+ install one of the apache2-mpm-* packages, such as worker or prefork.
Package: apache2-mpm-worker
Architecture: any
@@ -33,40 +30,44 @@
Provides: apache2-mpm, apache2, httpd, httpd-cgi
Conflicts: apache2-mpm, apache2-common
Replaces: apache2-mpm-threadpool (<< 2.0.53), apache2-mpm-perchild (<< 2.2.0)
-Description: High speed threaded model for Apache HTTPD
- The worker MPM provides a threaded implementation for Apache HTTPD. It is
- considerably faster than the traditional model, and is the recommended MPM.
- .
- Worker generally is a good choice for high-traffic servers because it
- has a smaller memory footprint than the prefork MPM.
+Description: Apache HTTP Server - high speed threaded model
+ Each Apache Multi-Processing Module provides a different "flavor" of
+ web server binary, compiled with a different processing model.
+ .
+ The worker MPM provides the default threaded implementation. It is
+ recommended especially for high-traffic sites because it is faster
+ and has a smaller memory footprint than the traditional prefork MPM.
Package: apache2-mpm-prefork
Architecture: any
Depends: ${shlibs:Depends}, apache2.2-common (= ${binary:Version})
Provides: apache2-mpm, apache2, httpd, httpd-cgi
Conflicts: apache2-mpm, apache2-common
-Description: Traditional model for Apache HTTPD
- This Multi-Processing Module (MPM) implements a non-threaded,
- pre-forking web server that handles requests in a manner similar to
- Apache 1.3. It is appropriate for sites that need to avoid threading for
- compatibility with non-thread-safe libraries. It is also the best MPM
- for isolating each request, so that a problem with a single request will
- not affect any other.
- .
- It is not as fast, but is considered to be more stable.
+Description: Apache HTTP Server - traditional non-threaded model
+ Each Apache Multi-Processing Module provides a different "flavor" of
+ web server binary, compiled with a different processing model.
+ .
+ The prefork MPM provides a non-threaded, pre-forking implementation
+ that handles requests in a manner similar to Apache 1.3. It is not as
+ fast as threaded models, but is considered to be more stable. It is
+ appropriate for sites that need to maintain compatibility with
+ non-thread-safe libraries, and is the best MPM for isolating each
+ request, so that a problem with a single request will not affect any
+ other.
Package: apache2-mpm-event
Architecture: any
Depends: ${shlibs:Depends}, apache2.2-common (= ${binary:Version})
Provides: apache2-mpm, apache2, httpd, httpd-cgi
Conflicts: apache2-mpm, apache2-common
-Description: Event driven model for Apache HTTPD
- The event Multi-Processing Module (MPM) is designed to allow more
- requests to be served simultaneously by passing off some processing
- work to supporting threads, freeing up the main threads to work on
- new requests.
- .
- This MPM is especially suitable for sites that see extensive KeepAlive traffic
+Description: Apache HTTP Server - event driven model
+ Each Apache Multi-Processing Module provides a different "flavor" of
+ web server binary, compiled with a different processing model.
+ .
+ The event MPM is designed to allow more requests to be served
+ simultaneously by passing off some processing work to supporting
+ threads, freeing up the main threads to work on new requests. It is
+ especially suitable for sites that see extensive KeepAlive traffic.
Package: apache2-mpm-perchild
Architecture: all
@@ -97,17 +98,21 @@
Architecture: all
Depends: apache2-mpm-worker (>= ${source:Version}) | apache2-mpm-prefork (>= ${source:Version}) | apache2-mpm-event (>= ${source:Version})
Section: web
-Description: Next generation, scalable, extendable web server
- Apache v2 is the next generation of the omnipresent Apache web server. This
- version - a total rewrite - introduces many new improvements, such as
- threading, a new API, IPv6 support, request/response filtering, and more.
+Description: Apache HTTP Server metapackage
+ The Apache Software Foundation's goal is to build a secure, efficient and
+ extensible HTTP server as standards-compliant open source software. The
+ result has long been the number one web server on the Internet.
+ .
+ It features support for HTTPS, virtual hosting, CGI and FastCGI, SSI,
+ IPv6, easy scripting and database integration, request/response
+ filtering, many flexible authentication schemes, and more.
Package: apache2-doc
Section: doc
Architecture: all
-Description: documentation for apache2
- This is the documentation for apache2, see the apache2 package description
- for more details.
+Description: Apache HTTP Server documentation
+ This package provides the documentation for Apache 2. For more details
+ see the apache2 package description.
Package: apache2-prefork-dev
Section: devel
@@ -115,12 +120,12 @@
Depends: apache2.2-common (= ${binary:Version}), openssl, libaprutil1-dev
Conflicts: apache2-threaded-dev
Priority: extra
-Description: development headers for apache2
+Description: Apache development headers - non-threaded MPM
This package provides the development headers and apxs2 binary for
apache2-mpm-prefork; see the apache2 package description for more details.
.
- This should only be used when you absolutely *have* to have a non-threaded
- environment, ie for PHP4.
+ This should only be used when you absolutely *must* support a non-threaded
+ environment (for PHP4, for example).
Package: apache2-threaded-dev
Section: devel
@@ -129,7 +134,7 @@
Conflicts: apache2-prefork-dev
Provides: apache2-dev
Priority: extra
-Description: development headers for apache2
+Description: Apache development headers - threaded MPM
This package provides the development headers and apxs2 binary for
threaded versions of apache2; see the apache2 package description
for more details.
Reply to: