Bug#1020248: debian-policy: Clarifying nomenclature for control file names

[Guillem Jover <guillem@debian.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