Bug#108416: Format of short description should be mandated

[Jim Penny <jpenny@debian.org>]

On Sat, Aug 11, 2001 at 06:56:58PM -0500, Branden Robinson wrote:
> 
> A package's short description should:
>  * fit on an 80-character line within the control file (so that the
>    package name and description together take up less than 80
>    characters)
>  * typically be written in a form that completes the following sentence:
>    "<foo> is a package which provides (a/an)..."
>  * expand acronyms that were coined for the purpose of naming the
>    package, if there is room and it is informative
>  * not attempt to explain or describe things to the user that he or she
>    would most likely already know if he or she wanted to install it
>    (For instance, most people who care anything about python or perl
>    packages know that these are scripting languages; it is not necessary
>    to reiterate that fact.)
> 
> A package's short description should not:
>  1. repeat the package name; package system front ends will not present
>     short descriptions in the absence of their corresponding package
>     names
>  2. refer to the names of any other software packages, protocl names,
>     standards, or specifications in their canonical forms (if one
>     exists)
>     (e.g.,
>     + "X Window System", "X11", or "X"; not "X Windows", "X-Windows", or
>       -- most hideous of all -- "X Window"
>     + "GTK+", not "GTK" or "gtk"
>     + "GNOME", not "Gnome"
>     + "PostScript", not "Postscript" or "postscript"
>  3. use the indefinite articles "a" or "an" where not strictly necessary;
>     especially not as the first word of the short description
>  4. contain capital letters or periods, except where required by 2)
>  5. refer to the fact that it is a Debian package (this is known from
>     context and is not new information)
>  6. use abbreviations like "&", "misc.", "etc.", or similar forms
> 

A question--

suppose you were packaging a database adapter

python-popy: database adapter

Seems a bit light.  Certainly you are going to have to say which
database the adapter adapts to.

python-popy: database adapter to PostgreSQL

Still seems light to me, we've mentioned the to, but not the from.
I suspect that the python- is a ambiguous for most readers.  Does
it mean something implemented in python, or does it mean something
that provides python infrastructure?  In fact, it means the latter
here.  It is actually implemented in C.

python-popy: module providing a database adapter from python to PostgreSQL

Who is the audience, is it an end-user tool or a programmer tool?


python-popy: module providing programmers a database adapter from python to PostgreSQL

Oops, 80 characters is now blown.

Further, there are multiple standards for python database APIs;
certainly, I would like to know as a programmer which standard
the program was attempting to follow:

python-popy: module providing programmers a database adapter from python to PostgreSQL using the Python Database API Specification 2.0

finally, the PDAPISv2.0 recognizes multiple levels of compliance,
python-popy happens to be at level 2.

python-popy: module providing programmers a database adapter from python to Pos
tgreSQL using the Python Database API Specification 2.0 (level 2 compliant)

I assert that in some sense, this is a minimal correct short description.

It can be shortened.  But even a confusing description hitting only the
keywords is more than 80 characters, e.g.
python-popy database adapter PostgreSQL Python Database API Specification 2.0 (level 2 compliant)

What is the correct solution?

Jim Penny
jpenny@debian.org