--- Begin Message ---
- To: submit@bugs.debian.org
- Subject: debian-policy: Clarifying nomenclature for control file names
- From: Guillem Jover <guillem@debian.org>
- Date: Sun, 18 Sep 2022 22:28:00 +0200
- Message-id: <Yyd/UN3Rxkb9kGzY@thunder.hadrons.org>
Package: debian-policy
Version: 4.6.1.1
Severity: wishlist
Hi!
This is a followup from my comment at:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=998165#43
To summarize, we have IMO confusing naming and nomenclature for the
various control files and paragraphs/stanzas, and this is even
confusing me when having to deal with dpkg code, so I'd like to give
these more clear and unambiguous new names, and I'd very strongly
prefer to agree on the same naming for Debian policy and dpkg, to
avoid further and worse confusion (even though they currently do not
match exactly anyway, but I'd prefer to not make it worse…).
Just for reference and to give some context, I've got the following
WIP branches, trying to clarify the names in documentation and in the
API on, which I'll probably rework (split/merge) and reword as needed,
so do not take them as anything set in stone:
https://git.hadrons.org/git/debian/dpkg/dpkg.git/log/?h=next/clarify-control-filenames
https://git.hadrons.org/git/debian/dpkg/dpkg.git/log/?h=next/deb822-field-types
File descriptions
-----------------
For example we have:
* debian/control:
policy → «Source package control file»
dpkg → «Debian source packages' master control file»
* .dsc:
policy → «Debian source control file»
dpkg → «Debian source packages' control file»
* DEBIAN/control
policy → «Binary package control files»
dpkg → «Debian binary packages' master control file»
These are quite confusingly close.
I've been considering naming debian/control something like
«Debian template source package control file», as that is used to
generate both the source and binary control files. And always
prefixing with Debian, so that would end up as:
* debian/control: «Debian source package template control file»
* .dsc: «Debian source package control file»
* DEBIAN/control: «Debian binary package control file»
This also removes the «master» usage in dpkg, for me for the same
reasons as I covered at
<https://lists.debian.org/debian-dpkg/2021/03/msg00002.html>.
File contents
-------------
We have references to the various parts being called as «paragraphs»,
«stanza», «blocks», but this seems to be more of an issue with dpkg, as
the usage in the Debian policy is quite clear and uniform now, so I'll
at least try to remove the «block» usage there, stanza has the nice
property of being shorter and policy already mentions that this is
currently a common alias, so I might keep paragraph and stanza for now
in dpkg.
The other thing affecting dpkg and debian-policy is how the parts
within the control files are referred to. We have for example:
dpkg → «general section of control info file»
«source stanza»
policy → «general paragraph»
dpkg → «package's section of control info file»
policy → «binary package paragraphs»
So, how does «source package paragraph» and «binary package paragraph»
(of the «template control file») sound instead?
If I've missed any other problematic nomenclature, I'm happy to
discuss and update those on the dpkg side.
Thanks,
Guillem
--- End Message ---
--- Begin Message ---
Source: debian-policy
Source-Version: 4.6.2.0
Done: Sean Whitton <spwhitton@spwhitton.name>
We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive.
A summary of the changes between this version and the previous one is
attached.
Thank you for reporting the bug, which will now be closed. If you
have further comments please address them to 1020248@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.
Debian distribution maintenance software
pp.
Sean Whitton <spwhitton@spwhitton.name> (supplier of updated debian-policy package)
(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Format: 1.8
Date: Fri, 16 Dec 2022 19:41:44 -0700
Source: debian-policy
Architecture: source
Version: 4.6.2.0
Distribution: unstable
Urgency: medium
Maintainer: Debian Policy Editors <debian-policy@lists.debian.org>
Changed-By: Sean Whitton <spwhitton@spwhitton.name>
Closes: 823256 953911 975631 992136 1020238 1020241 1020243 1020248 1020267
Changes:
debian-policy (4.6.2.0) unstable; urgency=medium
.
[ Sean Whitton ]
* Policy: Update alternatives system priorities for window managers
Wording: Ansgar <ansgar@debian.org>
Seconded: Russ Allbery <rra@debian.org>
Seconded: Sean Whitton <spwhitton@spwhitton.name>
Closes: #975631
* Policy: Clarify udeb-only source packages are out of scope
Wording: Russ Allbery <rra@debian.org>
Seconded: Holger Levsen <holger@layer-acht.org>
Seconded: Sean Whitton <spwhitton@spwhitton.name>
Closes: #992136
.
[ Russ Allbery ]
* Policy: Add new-version argument to several maintainer script calls
Wording: Russ Allbery <rra@debian.org>
Seconded: Sean Whitton <spwhitton@spwhitton.name>
Seconded: Guillem Jover <guillem@debian.org>
Closes: #823256
* Policy: Essential packages must work only if previously configured
Wording: Helmut Grohne <helmut@subdivi.de>
Seconded: Santiago Vila <sanvila@unex.es>
Seconded: Guillem Jover <guillem@hadrons.org>
Closes: #1020267
* Prefer "portion" to "stanza" when describing parts of the Vcs-Git
header to avoid confusion with blocks of fields in deb822. Thanks to
Charles Plessy for pointing out the inconsistency.
.
[ Guillem Jover ]
* Terminology fixes. (Closes: #1020248)
- Refer to blocks of fields in deb822 files as stanzas, not
paragraphs. This aligns terminology with dpkg and reduces confusion
with text paragraphs found in, for example, the Description field.
* Policy: Replace references to PGP with OpenPGP. (Closes: #1020243)
* Whitespace and quoting fixes. (Closes: #1020238)
- Remove trailing whitespace and convert tabs to spaces in all files.
- Avoid use of unbalanced single quotes.
* copyright-format: Formatting improvements. (Closes: #1020241)
- Put Source after Format in examples.
- Reformat GPL examples to be more compact.
- Use URLs rather than postal addresses in GPL examples.
- Move the comment about where the GPL can be found on Debian systems
to a separate Comment block in examples, rather than including it in
the License text.
- Apply wrap-and-sort -ast formatting to Files fields in the examples.
.
[ Daniel Shahaf ]
* Add an English description of the format of bug closers in the
changelog file, alongside the Perl-compatible regular expression.
(Closes: #953911)
Checksums-Sha1:
68020ea0f9df088391fed23bc80416df72e487c4 2110 debian-policy_4.6.2.0.dsc
043fcb99be4d3d2baf8df2f8ca6de851f0f65952 553052 debian-policy_4.6.2.0.tar.xz
Checksums-Sha256:
0a218d72f61712c86b66a1230cafde57ac73ee86f0a7994dcdc821f98c798d6f 2110 debian-policy_4.6.2.0.dsc
9ac321d91c6f6172d73fa7f6a59559e2f6d4b764921e2334ce6f891c11dde09f 553052 debian-policy_4.6.2.0.tar.xz
Files:
4c6e9d77f982a692fa26de9cc65a7002 2110 doc optional debian-policy_4.6.2.0.dsc
a9019d3ec96a9c6992050ea4ffd43f96 553052 doc optional debian-policy_4.6.2.0.tar.xz
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAmOdLJIACgkQaVt65L8G
YkAHZA//ZX0MECFXMtReEBV8qEolC+vwdewHyRLvbu9NrIRk1Wja+FuwCU1w9sP4
U1lmzDCTNkWoweme98tsqRw0umfZCQRBJAC9GEMqRFZQqEYShfYxATFiLV9ya2q9
oKt1NisN/83hrJUbd5FtR02LUVty06OaDTH+IeUa6NpoPTtY0vDrl1YXjrPMmH08
2gJwcHViR6rk6RRPZJZMRFEslkM3RyoiWecapU3oFLtscYMq+BPi4vsBhKqQ7C39
xn0M8t7hWcHzt4Kb9MT2aT89KaR7aCnvtgZZqCDvteAKdvwnnIbKJKqC9M+D8I2j
AE9zYd/6u/0zy0T74FrQ8y9SHVcGb7nY7tEGOsfJ2MekpllubxMQ4DiP3uGHbOBm
q/eyeOtxeD9kk7ONmUCkEXwIz292hRSyEh+WEr2zTf7HqEKeR6zik6UUn8oLJWCv
UCUitgdPJyUS4EYnY3n79vvIoTXuu/3LeWAvlh9k02avTeGFLEybKBg0kTV6m9z0
26OaxEFMco5XFIC7CZTeNj0LQttP+C3Pck3K7imfBr6IFNDOsEhION6JXm19AB6W
CU7BpFFiLQxuHhHSLzgIbuQE+KyywgReXUf339qQGbgD8jHeMBl6EECFaKTWPlA0
nd885fjVrXMchyj+dtQc+BOFB6EOH1sBwNjug5jbPxbjI6a6fHc=
=C64N
-----END PGP SIGNATURE-----
--- End Message ---