From: aph <aph@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sun, 23 Feb 2003 08:49:06 +0000 (+0000)
Subject: rework "Best practices for debian/control" based on contributions from
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=bc066cf3b9ecfd136d824d950c7d601a64cea47c;p=developers-reference.git

rework "Best practices for debian/control" based on contributions from
Colin Walters, Branden Robinson, and discussions on bugs 139957 and
108416


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

diff --git a/debian/changelog b/debian/changelog
index 083e200..b7cfb8e 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,10 +1,10 @@
 developers-reference (3.3) unstable; urgency=low
 
   * Frédéric Bothamy:
-    - French translation update to latest version
-    - Proofread by Philippe Batailler
+    - French translation update to version 3.2.2 (more or less)
+    - proofread by Philippe Batailler
   * Raphaël Hertzog:
-    - Added "ddtp" keyword in the PTS documentation.
+    - added "ddtp" keyword in the PTS documentation
   * Josip Rodin:
     - split out the doc-files per language, closes: #177448
     - shuffled stuff around in the packages chapter
@@ -28,7 +28,10 @@ developers-reference (3.3) unstable; urgency=low
       package descriptions are in English until UTF8 control files are
       allowed; proper escaping of single quotes here requires newest
       debhelper
-    - editorial changes on the additions in this release
+    - editorial changes on material added in this version
+    - rework "Best practices for debian/control" based on contributions
+      from Colin Walters, Branden Robinson, and discussions on bugs 139957
+      and 108416
 
  -- Adam Di Carlo <aph@debian.org>  
 
diff --git a/developers-reference.sgml b/developers-reference.sgml
index 3c41cbe..098d58b 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.186 $">
+  <!entity cvs-rev "$Revision: 1.187 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -3151,38 +3151,99 @@ this problem, though.
     <sect id="bpp-debian-control">
 	<heading>Best practices for <file>debian/control</file></heading>
         <p>
-The following practices supplement the <url
-            id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
-            name="Policy on package descriptions">.</p>
+The following practices are relevant to the
+<file>debian/control</file> file.  They supplement the <url
+id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
+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.
+
+
+
+	<sect1 id="bpp-desc-basics">
+          <heading>General guidelines for package descriptions</heading>
+          <p>
+The package description should be written for the average likely user,
+the average person who will use and benefit from the package.  For
+instance, development packages are for developers, and can be
+technical in their language.  More general-purpose applications, such
+as editors, should be written for a less technical user.
+          <p>
+Our review of package descriptions lead us to conclude that most
+package descriptions are technical, that is, are not written to make
+sense for non-technical users.  Unless your package really is only for
+technical users, this is a problem.
+          <p>
+How do you write for non-technical users?  Avoid jargon.  Avoid
+referring to other applications or frameworks that the user might not
+be familiar with &mdash; "GNOME" or "KDE" is fine, but "GTK+" is
+probably not.  Try not to assume any knowledge at all.  If you must
+use technical terms, introduce them.
+          <p>
+References to the names of any other software packages, protocol names,
+standards, or specifications should use their canonical forms, if one
+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 id="bpp-pkg-synopsis">
+          <heading>The package synopsis, or short description</heading>
+	    <p>
+The synopsis line (the short description) should be concise.  It
+must not repeat the package's name (this is policy).
+	    <p>
+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).  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 id="bpp-pkg-desc">
-	    <heading>Writing useful descriptions</heading>
+          <heading>The long description</heading>
 	    <p>
-The description of the package (as defined by the corresponding field
-in the <file>control</file> file) is the primary information available
-to the user about a package before they install it.  It should provide
-all the required information to let the user decide whether to install
-the package.
+The long description is the primary information available to the user
+about a package before they install it.  It should provide all the
+information needed to let the user decide whether to install the
+package.  Assume that the user has already read the package synopsis.
 	    <p>
-The following practices supplement the <url name="Policy on the descriptions
-of packages" id="&url-debian-policy;ch-miscellaneous.html#s-descriptions">.
+The long description should consist of full and complete sentences.
+It is recommended to use two spaces after full stops in sentences.  We
+realize this is an American style rather than European, but it is
+additionally helpful in creating visual space in fixed-width fonts.
 	    <p>
-The synopsis line (the short description) should primarily be concise.
-You may capitalize the first letter for aesthetics. It is customary to
-make the synopsis an appositive clause (not a full sentence) in which
-case there's no need to put a full stop (period) at the end.
+The first paragraph of the long description should answer the
+following questions: what does the package do?  what task does it help
+the user accomplish?  It is important to describe this in a
+non-technical way, unless of course the audience for the package is
+necessarily technical.
 	    <p>
-The long description should, however, always consist of full sentences.
+The following paragraphs should answer the following questions: Why do
+I as a user need this package?  What other features does the package
+have?  What outstanding features and deficiencies are there compared
+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>
-Since the first user impression is based on the description, be
-careful to avoid spelling and grammar mistakes. Ensure that you
+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>
 
-If you want someone to proofread the description that you
-intend to use you may ask on &email-debian-l10n-english;.
         </sect1>
 
         <sect1 id="bpp-upstream-info">