On Sat, Aug 11, 2001 at 08:02:08PM +0200, Sebastian Rittau wrote: > Package: debian-policy > Version: 22.214.171.124 > 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 email@example.com | Dad...not screaming in terror like http://people.debian.org/~branden/ | his passengers.
Description: PGP signature