some changes to bpp-debian-control from Sebastian Rittau

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

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 098d58b2abfb74fdd340361d737f378e312ce83d..2e1f386660b1da6d660525d6f07ead39e5591a1b 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.187 $">
+  <!entity cvs-rev "$Revision: 1.188 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -3146,9 +3146,10 @@ not on the root partition. That is, it's in <file>/usr/bin</file> rather
 than <file>/bin</file>, so one can't use it in scripts which are run
 before the <file>/usr</file> partition is mounted. Most scripts won't have
 this problem, though.
+      </sect>
 
 
-    <sect id="bpp-debian-control">
+      <sect id="bpp-debian-control">
        <heading>Best practices for <file>debian/control</file></heading>
         <p>
 The following practices are relevant to the
@@ -3161,7 +3162,6 @@ in the <file>control</file> file, contains both the package synopsis
 and the long description for the package.
 
 
-
        <sect1 id="bpp-desc-basics">
           <heading>General guidelines for package descriptions</heading>
           <p>
@@ -3188,6 +3188,7 @@ exists.  For example, use "X Window System", "X11", or "X"; not "X
 Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
 Use "GNOME", not "Gnome".  Use "PostScript", not "Postscript" or
 "postscript".
+        </sect1>
 
 
        <sect1 id="bpp-pkg-synopsis">
@@ -3206,11 +3207,7 @@ end with a full stop (period).  Imagine that the synopsis is combined
 with the package name in the following way:
 
 <example>The <var>package-name</var> is a <var>synopsis</var>.</example>
-           <p>
-If the package name is an acronym, it is sometimes useful to expand
-the acronym.  For instance, the synopsis for <package>vim</package> is
-"Vi IMproved - enhanced vi editor".
-
+        </sect1>
 
        <sect1 id="bpp-pkg-desc">
           <heading>The long description</heading>
@@ -3238,14 +3235,18 @@ to other packages (e.g., "if you need X, use Y instead")?  Is this
 package related to other packages in some way that is not handled by
 the package manager (e.g., "this is the client to the foo server")?
            <p>
+Be objective.  Package descriptions are not the place for advocating
+your package, no matter how much you love it.  Remember that the
+reader may not care about the same things you care about.
+           <p>
 Be careful to avoid spelling and grammar mistakes. Ensure that you
 spell-check it.  <prgn>ispell</prgn> has a special <tt>-g</tt> option
 for <file>debian/control</file> files:
 
 <example>ispell -d american -g debian/control</example>
-
         </sect1>
 
+
         <sect1 id="bpp-upstream-info">
           <heading>Upstream home page</heading>
           <p>
@@ -3262,7 +3263,7 @@ correctly.  To see an example of how this displays, see <url
 id="&url-eg-desc-upstream-info;">.
           <p>
 If there is no home page for the software, this should naturally be
-left empty.
+left out.
           <p>
 Note that we expect this field will eventually be replaced by a proper
 <file>debian/control</file> field understood by <prgn>dpkg</prgn> and