Bug#108416: Format of short description should be mandated
On Sat, Aug 18, 2001 at 11:06:36PM -0500, Branden Robinson wrote:
> Well, if I downgrade my "must not"'s to "should not"'s, would you second
> the proposal?
That wasn't addressed to me, but my reaction is the same as it was to
the original proposal: this doesn't belong in policy. It belongs in
dev-ref or the packaging manual, or some similar set of guidelines for
maintainers.
Policy is not required to file bugs (minor for typos, wishlist for
"unaestheticness") against package descriptions. All it does is allow
severity escalation. Having some guidelines somewhere would be good,
because it would allow us to move towards the goal of greater
consistency. But I still say that policy is not the place for such
guidelines.
That said, here are some specific comments on details of Branden's
proposal:
> * typically be written in a form that completes the following sentence:
> "<foo> is a package which provides (a/an)..."
The word "typically" reveals the flaw here, I think. "It should be
unless it shouldn't be." This is clearly just a guideline, and not
even a firm one, and thus, definitely doesn't belong in policy (even
if other parts of the proposal are accepted).
> * expand acronyms [...]
Generally, but not necessarily always, a good idea. IMO. I'd like to
see this as a guideline. I do not want to see it made policy.
Counter-example: a package named "httpd" shouldn't necessarily have to
exand "Hyper Text Transfer Protocol Daemon" in the one-liner. We
know. And sometimes the expansion of an acronym is a humorous
afterthought: "Little Instructive New Unixlike Xystem" :-)
> * 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 [...]
Here I strongly disagree. I think the one line description should be
targetted at people who _don't_ have any idea what the package is.
> [should not] repeat the package name [...]
Hmm, if any part of this proposal belongs in policy, it's this. But I
still think a guideline is sufficient.
> [should not] refer to the names of other packages, protocols, [etc.]
> in their canonical forms.
A) I think this is backwards (typo, no doubt), and B) doesn't deserve
to be more than a guideline. (Plus, I loathe "l33t" mixed-case names
like PostScript and NeXT, and I don't care if it's canonical or not!)
Furthermore, what about things like "MUA"? Arguable a canonical form,
but I don't think it belongs in a short description.
> [should not] use indefinite articles where not necessary.
Yuck. I'm not even sure this belongs in guidelines.
> [should not] use abbreviations
Piffle! I'm not going to spell out "etcetera".
> [must not] be identical to the short description of another package.
I think that _related_ packages should not have identical short
descriptions (e.g. gcc, xemacs), but if two unrelated packages end up
with identical short descriptions, I'm not sure it'll kill us.
(e.g. "graphical mail reader using GTK+ toolkit".)
> [must not] be longer than 80 chars.
Finally something I agree with! :-)
cheers
--
Chris Waters | Pneumonoultra- osis is too long
xtifr@debian.org | microscopicsilico- to fit into a single
or xtifr@speakeasy.net | volcaniconi- standalone haiku
Reply to: