added a link to the policy, and explained the current practice in the synopsis sectio...

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

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 07cc7af3b37b9c351e465de252049262df5896bc..6081314d48e92d371348b2644849ac6ad0201261 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.173 $">
+  <!entity cvs-rev "$Revision: 1.174 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -3140,9 +3140,15 @@ 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.
            <p>
-For consistency and aesthetics, you should capitalize the first letter
-of the Synopsis.  Don't put a full stop (period) at the end.  The
-description itself should consist of full sentences.
+The following practices supplement the <url name="Policy on the descriptions
+of packages" id="&url-debian-policy;ch-miscellaneous.html#s-descriptions">.
+           <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.
+           <p>
+The long description should, however, always consist of full sentences.
            <p>
 Since the first user impression is based on the description, be
 careful to avoid spelling and grammar mistakes. Ensure that you