Bug#536889: [developers-reference]: Please add an example for the short description starting with a verb
Hi Justin,
sorry for the delay ...
On Tue, 14 Jul, 2009 at 06:06:13PM +0100, Justin B Rye wrote:
> 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.
<quote>
It should also omit any initial indefinite or definite article - "a", "an",
or "the". Thus for instance:
Package: libeg0
Description: exemplification support library
Technically this is a noun phrase minus articles, as opposed to a verb
phrase.
</quote>
Please note that this is not good formulated. I assumed that the last
sentence just referred to the given example and not to the general rule.
Because of this it's currently also possible to just omit this sentence.
> Or does it just need to give more examples? Maybe examples of what
> _isn't_ right?
Since package description are important and since each change requires 20
translators to jump in and update translations more examples would be good.
This also increases consistence which is good (simplifies the search
patterns one has to start "apt-cache search" with, ...).
I never considered e.g. the example of a verb phrase starting with a anoun
you gave in your last mail :-)
On Fri, Jul 17, 2009 at 12:40:25PM +0100, Justin B Rye wrote:
> Justin B Rye wrote:
> > 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?
>
> I'd also be inclined to retitle this bug to something like
> "[developers-reference]: explicitly deprecate verb phrase synopses",
> but I'd prefer to hear from you before I do that.
Yep, this is fine with me.
> The only reliable way for non-specialists to tell whether a phrase
> obeys the guidelines is to slot it into the heuristic template and
> see if it fits.
OK, in this case please emphasise that the heuristic template has to fit.
Currently:
"A good heuristic is that it should be possible to substitute the
package name and synopsis into this formula:".
All descriptions which do not match this are not necessarily bad, at least
following mathematical logic. I also considered a slightly variation of
the template ("The package <name> <synopsis>") (so that it fits verbs)
acceptable.
Maybe this should be rephrased to:
"It is strongly suggested that the package synopsis fits the following
template:"
Weaker alternative:
"In general the package synopsis should fit the following template:"
The advantage of such an authoritative template is that one can easily
determine if a description is OK or not. In the initial example I gave
I really assumed a grammatical error, other people interpreted the synposis
differently and considered my usage as error.
Nevertheless I assume no package manager can display the (filled) template
as it is probably hard to translate.
Jens
Reply to: