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
