Package: developers-reference
Version: 3.4.1
Severity: normal
Tags: patch
This report has been brewing on debian-l10n-english for years - see
"http://lists.debian.org/debian-l10n-english/2008/08/msg00004.html";
The advice in DevRef 6.2.2 about package short descriptions is good,
but it's undermined by the fact that the rationale given is hogwash.
For a start:
# An appositive clause is defined in WordNet as a grammatical
# relation between a word and a noun phrase
Alas, valid package synopses are _not_ appositive clauses (indeed,
they're neither appositive nor clauses); clauses are not grammatical
relations; and what's more, WordNet has no such entry.
Now, the use of this kind of pseudoscientific gobbledygook in
justification for a rule may offend me as a linguistics graduate,
but that doesn't mean I want to see it replaced with an accurate
version. Even if every word of it was true, it would still be a bad
idea to base policy guidelines on a set of formal syntactic
principles, since most Debian package maintainers have had no
particular training in English syntactic analysis.
Besides, the grammatical rules clearly aren't the real reason for
the rule. If we're going to justify our advice, we should explain
it in terms of the real benefits it brings, such as that
standardising makes it easier for users to browse through a list of
short descriptions.
My patch concentrates on providing templates that developers can fit
their proposed synopses into. If you're interested in thrashing out
details of the wording, now would be a good time to bring it back to
debian-l10n-engl...@lists.debian.org, since there are more posters
around than usual.
--
JBR Uqarituukasippungaasiit (one word in West Greenlandic)
"Silly me, I went and spoke out of turn as usual!"
diff -ru ../developers-reference-3.4.0.pristine/best-pkging-practices.dbk ./best-pkging-practices.dbk
--- ../developers-reference-3.4.0.pristine/best-pkging-practices.dbk 2008-06-02 11:29:07.000000000 +0100
+++ ./best-pkging-practices.dbk 2009-02-20 20:53:11.000000000 +0000
@@ -210,41 +210,50 @@
<section id="bpp-pkg-synopsis">
<title>The package synopsis, or short description</title>
<para>
-The synopsis line (the short description) should be concise. It must not
-repeat the package's name (this is policy).
+Policy says the synopsis line (the short description) must be concise, not
+repeating the package name, but also informative.
</para>
<para>
-It's a good idea to think of the synopsis as an appositive clause, not a full
-sentence. An appositive clause is defined in WordNet as a grammatical relation
-between a word and a noun phrase that follows, e.g., Rudolph the red-nosed
-reindeer. The appositive clause here is red-nosed reindeer. Since the
-synopsis is a clause, rather than a full sentence, we recommend that it neither
-start with a capital nor end with a full stop (period). It should also not
-begin with an article, either definite (the) or indefinite (a or an).
-</para>
-<para>
-It might help to imagine that the synopsis is combined with the package name in
-the following way:
+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:
</para>
<screen>
-<replaceable>package-name</replaceable> is a <replaceable>synopsis</replaceable>.
+Package: libeg0
+Description: exemplification support library
</screen>
<para>
-Alternatively, it might make sense to think of it as
+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:
</para>
-<screen>
-<replaceable>package-name</replaceable> is <replaceable>synopsis</replaceable>.
-</screen>
<para>
-or, if the package name itself is a plural (such as developers-tools)
+The package <replaceable>name</replaceable> provides {a,an,the,some}
+<replaceable>synopsis</replaceable>.
+</para>
+<para>
+Sets of related packages may use an alternative scheme that divides the
+synopsis into two parts, the first a description of the whole suite and the
+second a summary of the package's role within it:
</para>
<screen>
-<replaceable>package-name</replaceable> are <replaceable>synopsis</replaceable>.
+Package: eg-tools
+Description: simple exemplification system (utilities)
+
+Package: eg-doc
+Description: simple exemplification system - documentation
</screen>
<para>
-This way of forming a sentence from the package name and synopsis should be
-considered as a heuristic and not a strict rule. There are some cases where it
-doesn't make sense to try to form a sentence.
+These synopses follow a modified formula. Where a package
+"<replaceable>name</replaceable>" has a synopsis
+"<replaceable>suite</replaceable> (<replaceable>role</replaceable>)" or
+"<replaceable>suite</replaceable> - <replaceable>role</replaceable>", the
+elements should be phrased so that they fit into the formula:
+</para>
+<para>
+The package <replaceable>name</replaceable> provides {a,an,the}
+<replaceable>role</replaceable> for the <replaceable>suite</replaceable>.
</para>
</section>
