the synopsis formula changed to either

[developers-reference.git] / developers-reference.sgml

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 22d7cadea67e12cdb77e7103c67ccaf99ada8a1f..3369c851e8762ee63fea7a7d0054362a346a320d 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.191 $">
+  <!entity cvs-rev "$Revision: 1.192 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -3101,8 +3101,11 @@ name="Policy on package descriptions">.
         <p>
 The description of the package, as defined by the corresponding field
 in the <file>control</file> file, contains both the package synopsis
-and the long description for the package.
-
+and the long description for the package.  <ref id="bpp-desc-basics">
+describes common guidelines for both parts of the package description.
+Following that, <ref id="bpp-pkg-synopsis"> provides guidelines
+specific to the synopsis, and <ref id="bpp-pkg-desc"> contains
+guidelines specific to the description.
 
        <sect1 id="bpp-desc-basics">
           <heading>General guidelines for package descriptions</heading>
@@ -3153,10 +3156,26 @@ 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).  Imagine that the synopsis is combined
-with the package name in the following way:
+end with a full stop (period).  It should also not begin with an
+article, either definite ("the") or indefinite ("a" or "an").
+           <p>
+It might help to imagine that the synopsis is combined with the
+package name in the following way:
+
+<example><var>package-name</var> is a <var>synopsis</var>.</example>
+
+Alternatively, it might make sense to think of it as
+
+<example><var>package-name</var> is <var>synopsis</var>.</example>
+
+or, if the package name itself is a plural (such as
+"developers-tools")
+
+<example><var>package-name</var> are <var>synopsis</var>.</example>
 
-<example>The <var>package-name</var> is a <var>synopsis</var>.</example>
+This way of forming a sentance 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 sentance.
         </sect1>
 
        <sect1 id="bpp-pkg-desc">
@@ -4376,6 +4395,8 @@ it.</p>
 <!-- FIXME: add the following
 
 questionable:
+  dbs (referred to above)
+  dpatch (referred to above)
   ucf
   dpkg-awk
   grep-dctrl