Bug#998165: debian-policy: document and allow Description in the source paragraph
Mattia Rizzolo <mattia@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.
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``.
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.
--
Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
Reply to: