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>
<!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 -->
<!--
<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>
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">
<!-- FIXME: add the following
questionable:
+ dbs (referred to above)
+ dpatch (referred to above)
ucf
dpkg-awk
grep-dctrl