Bug#536889: [developers-reference]: Please add an example for the short description starting with a verb
# for the control server:
retitle 536889 [developers-reference]: explicitly deprecate verb phrase synopses
thanks
The next step is to get your comments together as something I can
conveniently point at in a post to debian-l10n-english. This may
take me some time, but I promise it'll be less than the year and a
half it took me to get my vague ideas into shape for bug #516436!
Currently, DevRef6.2.2 says:
# The synopsis functions as a phrase describing the package, not a
# complete sentence, so sentential punctuation is inappropriate: it
# does not need extra capital letters or a final period (full stop).
# 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. 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>.
Criticisms:
1) basically, it's not clear that verb phrases are the main thing
we're deprecating;
2) in particular, the "noun phrase/verb phrase" part can be read as
an incidental description of the given example;
3) more examples (both "should" and "should not") would be good;
4) "a good heuristic" also makes it sound as if fitting the template
is optional. (Yes, the underlying definition is a matter of
syntax, but since developers don't usually think in terms of
noun phrases or verb phrases, the "heuristic" is the only
practical validation mechanism.)
You also mention the issue of translations. I don't know if we'd
want to even try to apply "the same rule" in languages that use
suffixed articles, or no articles at all! And Verb-Subject-Object
languages like Welsh would make things even trickier...
--
JBR
Ankh kak! (Ancient Egyptian blessing)
Reply to: