Package: mercurial-server
Version: 0.9-1
Severity: wishlist
Tags: patch
Hi! You may or may not be aware that I've been haunting the
debian-l10n-english mailinglist, trying among other things to
encourage developers to follow the DevRef6.2 guidelines on package
descriptions. One of those guidelines is that the short description
should be a Noun Phrase (minus articles) referring to the package
contents - or to put that in more useful terms, it should fit the
template "$PACKAGE provides a/the/some $SYNOPSIS". Yours on the
other hand fits the template "$PACKAGE lets you $SYNOPSIS" (or
perhaps "$PACKAGE is designed to $SYNOPSIS"), which means it's
(closer to) a Verb Phrase.
Now, phrases like that are common as "apropos" output, and package
descriptions are often copied directly from either a man page or an
upstream website, but both sources have drawbacks. Web pages tend
to be full of irrelevant enthusiasm about how open-source and easy
to compile the software is; man pages tend to assume the reader is
already familiar with the purpose of the software.
Before you ask, the logic of standardising on Noun Phrases goes like
this:
* Browsing through lists of descriptions is easier when they're
parallel, and the quickest way of improving browsability is to
encourage the use of the format that's already ahead.
* Individual executables may have a single function easily
summarised by a Verb Phrase, but packages aren't executables;
using a Noun Phrase makes packages like x11-common, coreutils,
or ttf-unifont easier to describe.
* Verb Phrase descriptions make it hard to tell at a glance what
general kind of thing a package provides - a daemon, a graphical
app, a set of commandline utilities?
The inherent vagueness is particularly unwelcome in the case of a
package named "mercurial-server" which doesn't in fact contain a
server binary! Instead I gather that the package is basically a set
of tools (and associated infrastructure) to let admins configure
Mercurial and SSH to work together. So it would be nice if the
synopsis said something like:
mercurial-server - toolkit for managing a shared Mercurial repository
My patch also capitalises "SSH" and "Mercurial" throughout on the
grounds that "ssh" is the command and "mercurial" is the package.
By the way, did you consider the option of naming it "Amalgam"?
-- System Information:
Debian Release: squeeze/sid
APT prefers testing
APT policy: (500, 'testing'), (50, 'unstable')
Architecture: i386 (i686)
Kernel: Linux 2.6.31.custom
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
--
JBR
Ankh kak! (Ancient Egyptian blessing)
diff -ru mercurial-server-0.9.pristine/debian/control mercurial-server-0.9/debian/control
--- mercurial-server-0.9.pristine/debian/control 2009-11-26 13:12:16.000000000 +0000
+++ mercurial-server-0.9/debian/control 2009-11-26 13:38:44.000000000 +0000
@@ -11,8 +11,8 @@
Package: mercurial-server
Architecture: all
Depends: ${shlibs:Depends}, ${misc:Depends}, ${python:Depends}, adduser, python, mercurial, openssh-server | ssh-server
-Description: provide and manage a shared Mercurial repository
+Description: toolkit for managing a shared Mercurial repository
mercurial-server makes a group of repositories available to the developers
- you choose, identified by ssh keys, with easy key and access management
- based on mercurial.
+ you choose, identified by SSH keys, with easy key and access management
+ based on Mercurial.
