Hello Mattia, Russ, Thank you both for your input on this.
On Mon 27 Dec 2021 at 09:51PM +01, Mattia Rizzolo wrote: > In my mind I was mostly focusing on being able to provide a > **description for the source package** (that is, then, relevant to > everything that source package builds); said description being picked up > by a substvar and used again later on is more like a nicety that comes > after describing the source first. On Mon 27 Dec 2021 at 01:53PM -08, Russ Allbery wrote: > Mattia Rizzolo <mat...@debian.org> writes: > >> |+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 used to >> |+describe the source package itself, and consequently all of the binary >> |+packages built from itself. > > What if we just left off that paragraph entirely? I'm not sure it's > adding anything. The new text would then read: > > In a source or binary control file, the ``Description`` field contains a > description of the package, consisting of two parts, the synopsis or > the short description, and the long description. > > If it's in a source control file, it's a description of the source > package; if it's in a binary control file, it's a description of the > binary package. That seems obvious, so I'm not sure we need to say it > explicitly. I had actually been thinking that the only point of a Description: field in the source package paragraph was for the sake of substituting it into binary package descriptions. Could those who have been involved in non-Policy discussions of source package paragraph Description: fields confirm that the purposes here really is to add descriptions for source packages, as well as to provide something to substitute? Introducing descriptions for source packages seems fine, but I want to be surer of our intent. > That said, 5.6.13 currently technically doesn't document Description for a > source package control file, only for source or binary control files or > (later, with entirely different syntax) for *.changes files. Maybe that's > the root of the problem. In that case, I think the paragraph we need is: > > The ``Description`` fields in source package control files are used to > construct the ``Description`` fields for the source and binary control > files when the package is built. Any ``Description`` field in the > first paragraph of the source package control file becomes the > description of the source package for the source binary control file. > ``Description`` fields in subsequent paragraphs become the description > of the corresponding binary packages. See deb-substvars(5) for some > substitution variables that may be useful when writing binary package > descriptions, such as ``source:Synopsis`` and > ``source:Extended-Description``. Looks good, once my question above is addressed. > BTW, I think "3.4 The description of the package" may also need some minor > updates. At the least, "Every Debian package" should probably say "Every > Debian binary package" since I don't think we're requiring source packages > to have descriptions. It may also be worth adding a paragraph explaining > that source packages may have descriptions as well, but are not required > to. Right. I don't think we even want to recommend them at this point. I would not like to put any pressure on maintainers to write them. -- Sean Whitton
signature.asc
Description: PGP signature
