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. 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 (r...@debian.org) <https://www.eyrie.org/~eagle/>