X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=best-pkging-practices.dbk;fp=best-pkging-practices.dbk;h=435bbba54e2a784f0f8db7115633525835aaf983;hb=2a3631b173d0f6ee192e8125daf43f81f6d187a4;hp=1f14722f71830b1d1c7fde3e52beb503d1dc2b72;hpb=521d0f89a6eb15625646bca4efa130fbd1c98294;p=developers-reference.git 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.