Bug#108416: Format of short description should be mandated
Joey Hess
> Since you're fond of statistics, here are some for woody/main/i386:
>
> $ grep '^Description:' Packages | wc -l
> 6126
> $ grep '^Description:' Packages | sort | uniq | wc -l
> 5848
> $ grep '^Description:' Packages | fold -w 93 | wc -l
> 6126
Unsuprising, since policy already says this:
The single line synopsis should be kept brief - certainly under 80
characters.
Lintian already checks for descriptions > 80 characters (and those > 60
as well, iirc). (I like the idea of surtracting the package name length
from description BTW.)
And I filed bugs on all packages that violated this rule within the past
year.
> Would that all the "musts" we actually *have* in policy could claim such
> success...
I guess it says something for policy not needing to be used as a stick;
a mere 'should' has clearly sufficed.
--
see shy jo
--
To UNSUBSCRIBE, email to debian-pol...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listm...@lists.debian.org
Branden Robinson
> I guess it says something for policy not needing to be used as a stick;
> a mere 'should' has clearly sufficed.
Well, if I downgrade my "must not"'s to "should not"'s, would you second
the proposal?
--
G. Branden Robinson | It was a typical net.exercise -- a
Debian GNU/Linux | screaming mob pounding on a greasy
bra...@debian.org | spot on the pavement, where used to
http://people.debian.org/~branden/ | lie the carcass of a dead horse.
Chris Waters
> 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
xt...@debian.org | microscopicsilico- to fit into a single
or xt...@speakeasy.net | volcaniconi- standalone haiku
Joey Hess
> 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?
I'm not sure, I have a terrific mail backlog and skimmed your proposal.
Chris makes some good points too, in the parts of his mail I have
deleted.
> 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.
> 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).
Please bear section 5.7.1 of debian policy in mind. Policy already has a
lot of guidelines about package descriptions. Many of them require the
application of common sense to be useful, but this is not unique in this
part of debian policy, and I belive that having them in a document that
every developer reads (I hope) has caused more good than harm.
> > * 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.
In this specific case, I really like what policy says now:
The description field needs to make sense to anyone, even people
who have no idea about any of the things the package deals with.
The acronym guidline falls out of this naturally. Maybe another footnote
could state it explicitly.
> 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.
I think policy agrees with you, see quote above.
> > [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.
Do not include the package name in the synopsis line.
Already in policy.
> > [must not] be longer than 80 chars.
>
> Finally something I agree with! :-)
Already in policy.
--
see shy jo
Manoj Srivastava
Branden> On Sat, Aug 18, 2001 at 11:05:59PM -0400, Joey Hess wrote:
>> I guess it says something for policy not needing to be used as a stick;
>> a mere 'should' has clearly sufficed.
Branden> Well, if I downgrade my "must not"'s to "should not"'s,
Branden> would you second the proposal?
Have you asked yourself whether this really needs a policy
dictum? (It does not, in my opinion. Recommended practice suggestions
ought to go into the developers reference; not policy).
manoj
--
Zimmerman's Law of Complaints: Nobody notices when things go right.
Manoj Srivastava <sriv...@debian.org> <http://www.debian.org/%7Esrivasta/>
1024R/C7261095 print CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Branden Robinson
> Have you asked yourself whether this really needs a policy
> dictum? (It does not, in my opinion. Recommended practice suggestions
> ought to go into the developers reference; not policy).
Is the Developers' Reference presently maintained?
--
G. Branden Robinson | The errors of great men are
Debian GNU/Linux | venerable because they are more
bra...@debian.org | fruitful than the truths of little
http://people.debian.org/~branden/ | men. -- Friedrich Nietzsche
Manoj Srivastava
Branden> Is the Developers' Reference presently maintained?
I would so assume. The maintainer, Adam Di Carlo, is fairly
active, and I would think that any proposed additions would be
incorporated. He has been releasing the reference at roughly monthly
intervals for most of the year.
manoj.
--
Ever get the feeling that the world's on tape and one of the reels is
missing? Rich Little
Sebastian Rittau
now. (I was not subscribed to debian-policy so I didn't follow the
discussion itself.) As the original bug-submitter I want to make
some final comments:
* I agree with most of Branden's proposal since it grants consistency
in package description. Consistency is important IMO, since the
current differences in package descriptions can easily make the
impression of "unprofessionalism".
* I do also agree with the people that said that this doesn't belong
into policy. The Developer's Reference is probably a better place
for it.
* As for the original discussion, whether we should mandate
capitalization/punctuation: The points that were made against this
were good IMO and I agree that lower case and no full stop should
be the "default".
- Sebastian
Branden Robinson
> 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.
I yield on the policy point, as long as we can have some language in the
Policy Manual that directs maintainers to look at the Developers'
Reference for guidelines on writing package descriptions.
> > * 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."
It's not quite that vague. "Typically" indicates that at the least the
majority of packages can be described thus. Do you disagree.
> > * expand acronyms [...]
[...]
> Counter-example: a package named "httpd" shouldn't necessarily have to
> exand "Hyper Text Transfer Protocol Daemon" in the one-liner. We
> know.
I find this assertion in tension with the one you make later that "the
one line description should be targetted at people who _don't_ have any
idea what the package is." Why would such people know what "HTTP"
stands for?
I think "httpd" would be a lousy name for a package, given that we have
more than one such tool in Debian, but if there were one called
"xtifr-httpd", I don't think "Chris Waters' Hypertext Transfer Protocol
Daemon" would be a bad short description.
> 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.
And I think there are cases where you simply can't educate people
sufficiently in 80 characters to enable them to make an informed
decision.
In Debian, there are packages that are typically installed by completely
novice end users; there are packages typically installed by Unix "power
users"; there are packages typically installed by experienced sysadmins;
there are packages typically installed by software developers. I think
short package descriptions in particular need to be appropriate for the
packages most characterstic audience.
I simply don't think there is a way in 80 characters to explain, for
example, an Emacs major mode package to someone who doesn't even know
exactly what is meant by "editor", let alone someone who doesn't know
what Emacs is, or that it is far more than just a text editor.
> > [should not] refer to the names of other packages, protocols, [etc.]
> > in their canonical forms.
>
> A) I think this is backwards (typo, no doubt)
Yes, it was a typo.
> (Plus, I loathe "l33t" mixed-case names
> like PostScript and NeXT, and I don't care if it's canonical or not!)
Some of these terms are trademarked and we could get into trouble for
misspelling or mis-casing them. I agree that studly caps or marketroid
caps are often silly and aggravating, but if we refer to such things
correctly (according to their coiners) and consistently, we help out our
users to do further independent research (say, Web searches), if they're
so inclined.
That said, I think there are cases like "NeXTSTEP" where the "canonical"
casing has changed many times, and everyone is out to sea if they dare
do a case-sensitive search. :) I do think this is the exception, not
the rule, however,
> Furthermore, what about things like "MUA"? Arguable a canonical form,
> but I don't think it belongs in a short description.
I would regard my goal of acronym expansion as secondary to the one
where we do our best to explain a package to its target audience. "Mail
User Agent" is a fairly sophisticated concept for the average email user
(most of whom aren't on Unix systems) these days.
> > [should not] use indefinite articles where not necessary.
>
> Yuck. I'm not even sure this belongs in guidelines.
I think they should be among the first things dropped if you're hitting
the length limit. Again, short descriptions aren't English sentences
and don't need to follow full English syntax rules.
> > [should not] use abbreviations
>
> Piffle! I'm not going to spell out "etcetera".
I would agree with that, but more to the point I don't think the term
"etc." should be in a package's short description in either abbreviated
or expanded form.
> > [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".)
I continue to think it is pretty important to throw users a bone, and
help them distinguish packages based on short description alone. Please
consider that, given the fact that we have something like 6000 packages
now, the short description is all that many users will *ever* see of a
package. User interfaces to the packaging system are under tremendous
pressure to provide a huge amount of information in a small space,
simply due to our package count.
--
G. Branden Robinson | The key to being a Southern
Debian GNU/Linux | Baptist: It ain't a sin if you
bra...@debian.org | don't get caught.
http://people.debian.org/~branden/ | -- Anthony Davidson
Steve Greenland
> I find this assertion in tension with the one you make later that "the
> one line description should be targetted at people who _don't_ have any
> idea what the package is." Why would such people know what "HTTP"
> stands for?
>
> I think "httpd" would be a lousy name for a package, given that we have
> more than one such tool in Debian, but if there were one called
> "xtifr-httpd", I don't think "Chris Waters' Hypertext Transfer Protocol
> Daemon" would be a bad short description.
I tend to agree in general, but in the specific case of HTTP daemons,
if you don't know what an "httpd" is, you probably don't need one, and
seeing "hypertext Transfer Protocol Daemon" isn't going to help. OTOH
(On The Other Hand, HTH), "Chris Waters' Web Server" is better than
either. Expanding "MP3 Player" seems silly. All of which leads me
to believe that expansion of acronyms should be left to the long
description. If there's a problem with a particular one, well, that's
what the BTS is for.
> And I think there are cases where you simply can't educate people
> sufficiently in 80 characters to enable them to make an informed
> decision.
Exactly.
Steve