[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#212814: please clarify 3.4: description of a package



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. <ballombe@debian.org>

Imagine a large red swirl here. 


Reply to: