From: aph <aph@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sat, 1 Mar 2003 19:10:23 +0000 (+0000)
Subject: the synopsis formula changed to either
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=9897b3b5f6b66ddca2a68b562455b1b13aa4f3c7

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 81a2bda..80e4ad3 100644
--- 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 22d7cad..3369c85 100644
--- 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