From 81dbd3451900dbfd840afe4564413f59b4cb0d9f Mon Sep 17 00:00:00 2001
From: joy <joy@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sat, 15 Feb 2003 12:03:51 +0000
Subject: [PATCH] added a link to the policy, and explained the current
 practice in the synopsis section. this is a compromise as it doesn't
 expressly conflict with Manoj's or jaq's POV :) closes: #174161

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2157 313b444b-1b9f-4f58-a734-7bb04f332e8d
---
 debian/changelog          |  2 ++
 developers-reference.sgml | 14 ++++++++++----
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index a7a69fb..3cbeb08 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -14,6 +14,8 @@ developers-reference (3.3) unstable; urgency=low
       kindly provided by Daniel Kobras, closes: #166388.
     - described debdiff and dpkg-depcheck, and linked to them from the
       right places in the document, closes: #172897.
+    - describe the current practice in writing synopsis lines,
+      closes: #174161.
   * Adam Di Carlo:
     - update (c) year
     - convert to debhelper (compat mode 4); maintainer scripts no longer
diff --git a/developers-reference.sgml b/developers-reference.sgml
index 07cc7af..6081314 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.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
-- 
2.30.2