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

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

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.

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

I don't quite understand what exactly does the Policy forbid and whether
it clashes with the current practice. Can anyone clarify and/or help me to
write a patch?


Attachment: signature.asc
Description: Digital signature

Reply to: