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: