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:
pgpgeoOFZtg8T.pgp
Description: PGP signature