Thanks for the swift response! I'm arguing my corner, but I may yet be able to come up with something you'll like.
Joey Hess wrote: > Justin B Rye wrote: >> There are a couple of stylesheet issue here (DevRef recommends >> against leading capitalisation and articles in synopses), but more >> significantly, the wording confuses /bin/gzip with gzip_*.deb >> throughout: >> * It claims that the package "is" the utility/compression tool. No, >> it "provides" that executable, and a handful of others. > > The typical way the package's description will be displayed is: > > gzip - The GNU compression utility > > This is the standard GNU file compression utility, which is also the > default > compression tool for Debian. It typically operates on files with names > ending in '.gz'. > > In which context both the short and long description make perfect sense; > they're referring to gzip, not the package. Yes, that's the problem: they're not referring to the thing they exist to describe. Package descriptions are (meant as) descriptions of packages - users who want a description of an individual executable should look at its man page. Now, upstream may think of "gzip" as the name of the whole GNU zip codebase. Upstream software development project names (trademarky things like, say, Xfce or Exim or GNU Emacs or Python) are different; they're routinely treated as interchangeable with the names of the programs they produce. If you're talking about _that_ gzip, it would be fair enough to say it does all these things; but that's "compression software", not "a compression utility". That reminds me: the package description treats it as obvious that gzip means "GNU zip". This point is IMHO more deserving of space than the insistence on how standardly GNUish it is - which amounts to nothing more than "it has been adopted as part of the GNU project", and is rather implied by the expansion as "GNU zip" anyway. > (I've always admired this particular package description for its brevity, > FWIW.) Brevity is the direction I always prefer to push in. For instance the synopsis would be briefer without that initial "The"... >> * The second paragraph explicitly states that the package can >> decompress things, and that just isn't true. > > "This package" and "the software contained in this package" are equvilant. If this was true, package descriptions wouldn't need language like "foo provides utilities to do bar" or "the 'baz' program does quux". You can say "Apache runs as a daemon", but only because Apache is the "trademark" name - it doesn't mean the Debian binary (meta)package apache2. >> * And yet reading "it" as /bin/gzip is still awkward, because that >> executable _doesn't_ typically operate on files with names >> ending in ".gz": > > Operation on files can include both reading them, and writing them. That reading's awkward to the point of being impossible: the .gz file doesn't even exist to be "operated on" until gzip has been invoked. If that's the intended interpretation, wouldn't it be simpler just to say that it _produces_ files with a .gz extension? How about this, a couple of lines shorter than the original: Description: GNU compression tools This package provides Debian's default compression software: the standard GNU zip, which can compress files, adding ".gz" to their names, or decompress both these and ".Z" files created by compress. If you don't like that, there's plenty of time to work on it; I'm certainly not expecting any of my suggestions to get into Lenny! -- JBR Ankh kak! (Ancient Egyptian blessing) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
