Bug#536889: [developers-reference]: Please add an example for the short description starting with a verb
Jens Seidel wrote:
> as described in #400970 the formulation of the short description starting
> with a verb is not clear. Chapter 6.2.2 suggests:
>
> "A good heuristic is that it should be possible to substitute the package
> name and synopsis into this formula:
>
> The package <name> provides {a,an,the,some} <synopsis>."
>
> Applying this to a package description as
> "display large colourful characters in text mode"
> one could guess that a 3rd person form is more suitable:
> "displays " ...
No; both are wrong and fail the heuristic. "Display things" is a
verb phrase; "displays things" is a verb phrase; and verb phrases
don't fit the formula. As the previous line of DevRef6.2.2 says,
what developers are meant to be using is a noun phrase (minus
articles), _not_ a verb phrase. Of course, DevRef guidelines aren't
legally binding, so a lot of package descriptions are malformed.
Since I'm the guy who came up with the current phrasing (of a
pre-existing recommendation; see bug #516436), I'd be interested to
hear what you'd suggest as a way of communicating this more clearly.
It was already obvious that technical terms alone wouldn't work
(because they're meaningless to non-linguists); but it seems the
substitution formula doesn't work very well either. Or does it just
need to give more examples? Maybe examples of what _isn't_ right?
In this specific case:
Package: toilet
Description: display large colourful characters in text mode
The problem with a synopsis like toilet's is that it doesn't say
what sort of thing this package is. What's needed is a description
that makes it clear to people browsing the package repositories
whether toilet is a:
- daemon that puts a scrolling marquee on the console
- font-setup utility for the partially sighted
- text banner generator using ASCII art
See? Those are all expressed so that they do fit the formula - "The
package toilet provides a... text banner generator using ASCII art".
Oh, and if that package description came to debian-l10n-english for
review I'd also en_USify the spellings and ask "why TOIlet?"
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: