Bug#998165: debian-policy: document and allow Description in the source paragraph

[Guillem Jover <guillem@debian.org>]

On Tue, 2021-12-21 at 17:53:31 -0700, Sean Whitton wrote:
> On Sun 12 Dec 2021 at 06:47PM +01, Mattia Rizzolo wrote:
> 
> > |--- a/policy/ch-controlfields.rst
> > |+++ b/policy/ch-controlfields.rst
> > |@@ -652,9 +654,14 @@ orderings.  [#]_
> > | ~~~~~~~~~~~~~~~
> > |
> > | In a source or binary control file, the ``Description`` field contains a
> > |-description of the binary package, consisting of two parts, the synopsis
> > |-or the short description, and the long description. It is a multiline
> > |-field with the following format:
> > |+description of the package, consisting of two parts, the synopsis or the short
> > |+description, and the long description.
> > |+
> > |+When used in a source control file in the general paragraph (i.e., the first
> > |+one, for the source package), the text in this field is relevant for all binary
> > |+packages built by the given source package.
> 
> Is there really no name for the first paragraph other than "general
> paragraph"?

That's how the dpkg documentation (man and perl modules POD) refers to
it (or first block of information, which is even worse), but I agree
it's rather suboptimal, and I'd like to get a better name for it. See
below.

> Maybe "the source package's stanza"?

Something like this might work, which is probably what we have been
calling it for some time now, but that ties up with something that has
been bothering me for some time now, and that is that I've found our
naming of the various stanzas and the various control filenames rather
confusingly similar, which for dpkg I'd really like to clear up (and
have few tentative commits already), as that's even affecting its perl
API currently. :/

For example we have «Debian source control file» or «Debian source
packages' control file» for .dsc, then we have «Source package control
file» or in dpkg «Debian source packages' master control file» for
debian/control. Which are almost the same. I've been considering naming
debian/control something like «Debian template source control file», as
that is used to generate both the source and binary control files.

But I think I'll open a new bug to cover and discuss that.

> Also, how about "the text in this field describes all binary packages
> which do not have their own Description: fields" ?

I'm not sure whether you are (or the text would then) imply this; but
the Description in the source stanza does not get inherited by the
binary stanzas when generating the binary package control file, one
needs to add references to it via substvars.

Thanks,
Guillem