From 2a3631b173d0f6ee192e8125daf43f81f6d187a4 Mon Sep 17 00:00:00 2001 From: lucas Date: Wed, 24 Jun 2009 15:37:12 +0000 Subject: [PATCH] fix #516436 (apply patch from Justin B Rye) git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@6753 313b444b-1b9f-4f58-a734-7bb04f332e8d --- best-pkging-practices.dbk | 55 +++++++++++++++++++++++---------------- debian/changelog | 5 ++-- 2 files changed, 35 insertions(+), 25 deletions(-) diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk index 1f14722..435bbba 100644 --- a/best-pkging-practices.dbk +++ b/best-pkging-practices.dbk @@ -210,41 +210,50 @@ along to &email-debian-l10n-english; and request feedback.
The package synopsis, or short description -The synopsis line (the short description) should be concise. It must not -repeat the package's name (this is policy). +Policy says the synopsis line (the short description) must be concise, not +repeating the package name, but also informative. -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). It should also not -begin with an article, either definite (the) or indefinite (a or an). - - -It might help to imagine that the synopsis is combined with the package name in -the following way: +The synopsis functions as a phrase describing the package, not a complete +sentence, so sentential punctuation is inappropriate: it does not need extra +capital letters or a final period (full stop). It should also omit any initial +indefinite or definite article - "a", "an", or "the". Thus for instance: -package-name is a synopsis. +Package: libeg0 +Description: exemplification support library -Alternatively, it might make sense to think of it as +Technically this is a noun phrase minus articles, as opposed to a verb phrase. +A good heuristic is that it should be possible to substitute the package name +and synopsis into this formula: - -package-name is synopsis. - -or, if the package name itself is a plural (such as developers-tools) +The package name provides {a,an,the,some} +synopsis. + + +Sets of related packages may use an alternative scheme that divides the +synopsis into two parts, the first a description of the whole suite and the +second a summary of the package's role within it: -package-name are synopsis. +Package: eg-tools +Description: simple exemplification system (utilities) + +Package: eg-doc +Description: simple exemplification system - documentation -This way of forming a sentence 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 sentence. +These synopses follow a modified formula. Where a package +"name" has a synopsis +"suite (role)" or +"suite - role", the +elements should be phrased so that they fit into the formula: + + +The package name provides {a,an,the} +role for the suite.
diff --git a/debian/changelog b/debian/changelog index dd85884..3fe69b7 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,8 +1,9 @@ developers-reference (3.4.2) UNRELEASED; urgency=low - * UNRELEASED. + * Applied patch from Justin B Rye that improves the discussion on writing + package descriptions. Closes: #516436. - -- Lucas Nussbaum Fri, 23 Jan 2009 10:36:40 +0100 + -- Lucas Nussbaum Wed, 24 Jun 2009 17:18:29 +0200 developers-reference (3.4.1) unstable; urgency=low -- 2.30.2