On Sat, Nov 22, 2014 at 12:22:19PM +0500, Andrey Rahmatullin wrote: > On Fri, Sep 26, 2003 at 10:55:44AM +0200, Matthias Klose wrote: > > triggered by #209693, the question is, if the long description should > > be understandable on its own, or together with the short description. > > > > Description: Documentation for an array processing package for Python > > This package contains the manual in PDF format. > > > > Clearly the long description is unreadable by itself. lintian on the > > other hand does check, if the short description is repeated in the > > long description. > > > > Proposing a change like: "the long description should always be > > displayed together with the synopsis, there is no need to repeat the > > synopsis in some form in the long description". > The current Policy text says: > > Do not try to continue the single line synopsis into the extended > description. This will not work correctly when the full description is > displayed, and makes no sense where only the summary (the single line > synopsis) is available.
This snippet is to prevent things like Description: PARI/GP Computer Algebra System designed for fast computations in number theory Even while package.d.o display both synopsis and long description, the result would look like """ Package: pari-gp <big>PARI/GP Computer Algebra System</big> designed for fast computations in number theory """" which would be awkward. > The current practice is to not repeat the synopsis and this is enforced by > lintian since 2002, with an E tag: > > Tag: description-synopsis-is-duplicated > Severity: important > Certainty: certain > Info: The first line of the extended Description: should not repeat the > synopsis exactly. This indicates that either the synopsis is badly formed > or that the extended description has been wrongly copied and pasted. > Ref: policy 3.4.2 The rationale given in Info: seems sufficient to me. Synopsis must not be a proper sentence, but the long description must be one. Thus, if the description starts by the synopsis, then something is grammatically amiss. Yes this is a bit crude as a test, but it detects a common error without having to use an English grammar analyzer. Cheers, -- Bill. <ballo...@debian.org> Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org