Bug#458029: package descriptions are unclear
Followup-For: Bug #458029
Package: apt
Version: 0.7.11
I've been looking through Essential for the package descriptions
most in need of a review (see #482098, #482666). Since apt already
has a BTS entry for this issue, I thought I'd better attach my
suggested patch to that report.
Philippe Cloutier wrote:
> The packages descriptions are unclear, particularly about what apt contains.
# Package: apt
# Description: Advanced front-end for dpkg
# This is Debian's next generation front-end for the dpkg package manager.
# It provides the apt-get utility and APT dselect method that provides a
# simpler, safer way to install and upgrade packages.
# .
# APT features complete installation ordering, multiple source capability
# and several other unique features, see the Users Guide in apt-doc.
Problems with the style:
------------------------
* Bogus capitalisation in synopsis.
* Within-sentence repetitions: "provides", "features".
* Unclear structure - depending on whether there's a missing article
or a failure of verb agreement, it might mean either:
1) It provides the apt-get utility, and the APT dselect
method, which [in turn] provides [...]
2) It provides the apt-get utility and APT dselect method,
which [together] provide [...]
* The final clause is a "comma splice".
* The Guide itself claims to be a User's Guide, with apostrophe.
Problems with the content:
--------------------------
* All this insistence on how advanced it is dates it badly; the Next
Generation was old hat ten years ago (when we all used
dselect). There's not much point singing the praises of an
Essential package anyway.
* As #458029 points out, the label "front-end" is misleading. From
an aptitude user's point of view, APT is somewhere in the
middle.
* The last paragraph is needlessly obscure. "Features... multiple
source capability" seems to mean "can handle multiple source
repositories", but what's "complete installation ordering"?
What are APT's "other unique features", and are its rivals
being monitored to ensure we stop claiming this when they
catch up? (I'm guessing no.)
* Either expand the acronym "A.P.T." somewhere here (not just in the
long description for apt-doc) or stop shouting Apt's name.
I concur with #458026 on "Advanced Package Tool" making more
sense than "Advanced Packaging Tool"; if it's important to
maintain "deniability" about the expansion being official,
it can be an implicit expansion in the short description.
My suggested replacement, drastically reorganised:
Package: apt
Description: Debian's advanced package tool
This package provides command-line utilities for package management,
including apt-get, used for finding and fetching software upgrades,
and apt-cache, used for interrogating the package database. It depends
on dpkg as its back-end for installs, and can be used either directly
or via high-level interfaces such as aptitude.
.
A User's Guide is available in the package apt-doc.
-- 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
Versions of packages apt depends on:
ii debian-archive-keyring 2008.04.16+nmu1 GnuPG archive keys of the Debian a
ii libc6 2.7-10 GNU C Library: Shared libraries
ii libgcc1 1:4.3.0-3 GCC support library
ii libstdc++6 4.3.0-3 The GNU Standard C++ Library v3
apt recommends no packages.
-- no debconf information
--
JBR
Ankh kak! (Ancient Egyptian blessing)
diff -ru apt-0.7.13.pristine/debian/control apt-0.7.13/debian/control
--- apt-0.7.13.pristine/debian/control 2008-05-02 16:05:25.000000000 +0100
+++ apt-0.7.13/debian/control 2008-05-25 18:30:30.000000000 +0100
@@ -15,13 +15,14 @@
Provides: ${libapt-pkg:provides}
Suggests: aptitude | synaptic | gnome-apt | wajig, dpkg-dev, apt-doc, bzip2, lzma
Section: admin
-Description: Advanced front-end for dpkg
- This is Debian's next generation front-end for the dpkg package manager.
- It provides the apt-get utility and APT dselect method that provides a
- simpler, safer way to install and upgrade packages.
+Description: Debian's advanced package tool
+ This package provides command-line utilities for package management,
+ including apt-get, used for finding and fetching software upgrades,
+ and apt-cache, used for interrogating the package database. It depends
+ on dpkg as its back-end for installs, and can be used either directly
+ or via high-level interfaces such as aptitude.
.
- APT features complete installation ordering, multiple source capability
- and several other unique features, see the Users Guide in apt-doc.
+ A User's Guide is available in the package apt-doc.
Package: apt-doc
Architecture: all
Reply to: