the synopsis formula changed to either

 <package-name> is a <synopsis>
or
 <package-name> is <synopsis>
or
 <package-name> are <synopsis>
closes: #182956

the synopsis itself should not start with an article

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2205 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/debian/changelog b/debian/changelog
index 81a2bda21745a357c07ea4762555c40615676abc..80e4ad3415b5bb8262334ece73947ec4413d38c0 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,6 +5,15 @@ developers-reference (3.3.1) unstable; urgency=low
       closes: #182614
   * Adam Di Carlo:
     - more improvements to package synopsis and description
+    - the synopsis formula changed to either
+       <package-name> is a <synopsis>
+      or
+       <package-name> is <synopsis>
+      or
+       <package-name> are <synopsis>
+      closes: #182956
+    - the synopsis itself should not start with an article
+    - Sec "Best practices for debian/control": expand into
 
  -- Adam Di Carlo <aph@debian.org>
 

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