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 <[EMAIL PROTECTED]> # Uploaders: Tollef Fog Heen <[EMAIL PROTECTED]>, Thom May <[EMAIL PROTECTED]>, Adam Conrad <[EMAIL PROTECTED]>, Peter Samuelson <[EMAIL PROTECTED]>, Stefan Fritsch <[EMAIL PROTECTED]> # 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.