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
