fix #516436 (apply patch from Justin B Rye)

[developers-reference.git] / best-pkging-practices.dbk

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 1f14722f71830b1d1c7fde3e52beb503d1dc2b72..435bbba54e2a784f0f8db7115633525835aaf983 100644 (file)
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -210,41 +210,50 @@ along to &email-debian-l10n-english; and request feedback.
 <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>