[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#108416: Format of short description should be mandated



On Sat, Aug 11, 2001 at 08:02:08PM +0200, Sebastian Rittau wrote:
> Package: debian-policy
> Version: 3.5.6.0
> Severity: wishlist
> 
> Currently, most package start the short package description with a
> capital letter, but some don't. Also, some short descriptions end
> with a period, some don't. I think, policy state, what is correct.
> (I would prefer capital letter and period, but that's just a personal
> preference.)

I disagree, but it's more important that Policy state what is preferred
than which side of this particular issue it falls on.

For instance, I don't believe packages' short descriptions should start
with a capital letter and end with a period because in most cases they
are not English sentences -- they thus need not conform to English
syntax rules.  This is an important point for short descriptions because
space is at a premium.

> Of course, policy shouldn't be too strict about that as there may be
> cases where for example a capital letter doesn't sense (e.g. aRts is a
> name that should be spelled just like that, also please respect
> non-english package description translations).

Agreed.

Here are some suggestions to get the ball rolling:

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 package's short description must not:
  * be identical to the short description of another package
  * be longer than 80 characters

Examples of IMO excellent short package descriptions:

Description: simple configuration tool for Japanese environment
	short, sweet, no excessive use of articles or punctutation

Description: Vi IMproved - enhanced vi editor
	explains package name "vim", and describes package in terms of
	well-known existing software

Description: reasonably versatile X-based image editing tool
	major props for not saying "X-Windows-based"

Description: Debian Packaging Manual

Description: Perl extensions for writing pRPC servers and clients
	(is "Perl" more canonical than "perl"?)

Description: an oscilloscope on acid
	exempted from the article rule because this description is
	clearly written with a touch of whimsy (as was the program, I
	think :) )

Examples of IMO "not-excellent" short package descriptions:

Description: The Japanese version of chess.
	gratuitous sentence form; lose the "The" and the period and it's
	fine
I suggest: Japanese version of chess

Description: Emacs-lisp python-mode for the scripting language Python.
	inconsistent capitalization of Python
	not sure "lisp" is canonical; I thought it was "LISP" (though
	this might not matter in the context of the distinct language of
	Emacs Lisp)
	ends with a period
I suggest: Emacs LISP major mode for the Python scripting language
or just: Emacs major mode for Python

Description: The GNU wdiff utility. Compares two files word by word.
	gratuitous caps, articles, and periods
I suggest: GNU "word-diff" utility for comparing files word by word

Description: A compression module for Python using zlib.
I suggest: zlib compression module for Python

Description: The telnet client.
I suggest: telnet client

Description: Frontends to DNS search.
	intial cap and period again
	not enough information, IMO
I suggest: programs to perform lookups on DNS servers

-- 
G. Branden Robinson                |     When I die I want to go peacefully
Debian GNU/Linux                   |     in my sleep like my ol' Grand
branden@debian.org                 |     Dad...not screaming in terror like
http://people.debian.org/~branden/ |     his passengers.

Attachment: pgpGqnD1WkLeq.pgp
Description: PGP signature


Reply to: