Bug#1020248: marked as done (debian-policy: Clarifying nomenclature for control file names)
Control: reopen -1
Hi!
Sorry, probably my fault! As I tend to use «Fixes:» git pseudo-fields
for things that fix part of a bug, but are not intended yet to close it,
for which I use «Closes:».
And for some reason I think I also got the impression, even though
the stanza changes had been committed, they could still be backed out.
(BTW I've now gone over the wiki and updated all paragraph references
that applied to stanza.)
In any case, I've sat down and gone over the meat of the original
report. See below.
On Sat, 2022-12-17 at 03:09:10 +0000, Debian Bug Tracking System wrote:
> Date: Sun, 18 Sep 2022 22:28:00 +0200
> From: Guillem Jover <guillem@debian.org>
> To: submit@bugs.debian.org
> Subject: debian-policy: Clarifying nomenclature for control file names
>
> Package: debian-policy
> Version: 4.6.1.1
> Severity: wishlist
> 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»
Seems I missed another file:
* .changes:
policy → «upload control file» / «Debian changes file»
dpkg → «upload control file» / «.changes control file» /
«Debian .changes file» / «Debian changes 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»
For changes I think something like the following might be a more clear
option (and has the minor bonus of aligning perfectly on the first
words! :), with it mentioning explicitly this is about changes being
uploaded, and that it is a control file (but I'm not sure I'm entirely
convinced about it):
* .changes: «Debian upload changes control files»
> 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.
I've also found instances of «record» and «section» referring to fields
or stanzas.
> 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.
I also recalled another term that has always seemed very confusing in
context: «control information files» or «control information area». For
example in a sentence such as “the control file is a control information
file in the control information area in a .deb archive”. :) This also
seems confusing when some of the files in the .deb control member are
not really “control files” with a deb822(5) format.
My thinking has been going into calling these as the «metadata files»,
and being located in either the «metadata part of the .deb archive» or
explicitly the «control member of the .deb archive», in contrast to the
filesystem part. In dpkg I'd be eventually switching to meta/metadata
and fsys/filesystem, from control or info and data. I've added a patch
with the proposed change, but again nothing set in stone, and I'm again
open to discussing pros/cons of this.
Attached the proposals for discussion/review, and I might again have
perhaps missed instances or similar.
Thanks,
Guillem
From a1494cbd64b48b7afa9145e208f91d243d4b384b Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@debian.org>
Date: Fri, 23 Sep 2022 12:30:22 +0200
Subject: [PATCH 1/6] =?UTF-8?q?Use=20=C2=ABfield=C2=BB=20instead=20of=20?=
=?UTF-8?q?=C2=ABrecord=C2=BB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
policy/ch-archive.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/policy/ch-archive.rst b/policy/ch-archive.rst
index ab04261..d04ad8f 100644
--- a/policy/ch-archive.rst
+++ b/policy/ch-archive.rst
@@ -265,7 +265,7 @@ The packages in the archive areas *main*, *contrib* and *non-free* are
grouped further into *sections* to simplify handling.
The archive area and section for each package should be specified in the
-package's ``Section`` control record (see
+package's ``Section`` control field (see
:ref:`s-f-Section`). However, the maintainer of the
Debian archive may override this selection to ensure the consistency of
the Debian distribution. The ``Section`` field should be of the form:
--
2.39.0
From b1881f638d4a734b9c6d8fa4d72809a0dc453740 Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@debian.org>
Date: Fri, 23 Sep 2022 12:30:22 +0200
Subject: [PATCH 2/6] =?UTF-8?q?Use=20=C2=ABstanza=C2=BB=20instead=20of=20?=
=?UTF-8?q?=C2=ABsection=C2=BB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
policy/ch-relationships.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index 5074428..c18050f 100644
--- a/policy/ch-relationships.rst
+++ b/policy/ch-relationships.rst
@@ -132,9 +132,9 @@ cpu, ``bar`` on architectures using any kernel and an i386 cpu, and
``baz`` on any architecture using a kernel other than Linux.
Note that the binary package relationship fields such as ``Depends``
-appear in one of the binary package sections of the control file,
+appear in one of the binary package stanzas of the control file,
whereas the build-time relationships such as ``Build-Depends`` appear in
-the source package section of the control file (which is the first
+the source package stanza of the control file (which is the first
section).
.. _s-binarydeps:
--
2.39.0
From dfb6c12b2fa58e3f75020cf6f6eb7ca7928e75a4 Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@debian.org>
Date: Fri, 23 Sep 2022 12:30:22 +0200
Subject: [PATCH 3/6] Markup Files field name
---
policy/ch-controlfields.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 4bab7df..ee65f5d 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -951,7 +951,7 @@ size in bytes, divided by 1024 and rounded up.
This field contains a list of files with information about each one. The
exact information and syntax varies with the context.
-In all cases, Files is a multiline field. The first line of the field
+In all cases, ``Files`` is a multiline field. The first line of the field
value (the part on the same line as ``Files:``) is always empty. The
content of the field is expressed as continuation lines, one line per
file. Each line must be indented by one space and contain a number of
--
2.39.0
From 7b125bfb04b5ba312dcf3d1a074dc7a78c154f36 Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@debian.org>
Date: Sat, 17 Dec 2022 13:47:08 +0100
Subject: [PATCH 4/6] =?UTF-8?q?Markup=20=C2=AB.changes=C2=BB=20and=20?=
=?UTF-8?q?=C2=AB.dsc=C2=BB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
policy/ch-controlfields.rst | 2 +-
policy/upgrading-checklist.rst | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index ee65f5d..3678c79 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -1008,7 +1008,7 @@ being uploaded.
~~~~~~~~~~
A space-separated list of bug report numbers that the upload governed by
-the .changes file closes.
+the ``.changes`` file closes.
.. _s-f-Homepage:
diff --git a/policy/upgrading-checklist.rst b/policy/upgrading-checklist.rst
index 8265016..c772b7e 100644
--- a/policy/upgrading-checklist.rst
+++ b/policy/upgrading-checklist.rst
@@ -1414,7 +1414,7 @@ menu policy
would be more appropriate.
5.6.1
- The Source field in a .changes file may contain a version number in
+ The Source field in a ``.changes`` file may contain a version number in
parentheses.
5.6.17
@@ -1553,7 +1553,7 @@ Many packaging manual appendices that were integrated into policy
sections are now empty, and replaced with links to the Policy. In
particular, the appendices that included the list of control fields
were updated (new fields like Closes, Changed-By were added) and the
-list of fields for each of control, .changes and .dsc files is now
+list of fields for each of control, ``.changes`` and ``.dsc`` files is now
in Policy, and they're marked mandatory, recommended or optional
based on the current practice and the behavior of the deb-building
tool-chain.
--
2.39.0
From 30d326533fc50cd517e960bbfb415458f29bbd90 Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@debian.org>
Date: Fri, 23 Sep 2022 12:30:22 +0200
Subject: [PATCH 5/6] Clarify terminology for Debian control files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Their current descriptive names are very close and easily confused if
one is not paying close attention. Use new terminology that try to
make them less ambiguous and intuitive.
The new and unified terms are:
* debian/control: «Debian source package template control file»
* .dsc: «Debian source package control file»
* DEBIAN/control: «Debian binary package control file»
* .changes: «Debian upload changes control file»
For contents we use these new terms:
First stanza in debian/control: «source package stanza»
Next stanzas in debian/control: «binary package stanza»
---
policy/ap-pkg-binarypkg.rst | 2 +-
policy/ap-pkg-sourcepkg.rst | 4 +--
policy/ch-controlfields.rst | 60 ++++++++++++++++++-------------------
policy/ch-relationships.rst | 8 ++---
4 files changed, 37 insertions(+), 37 deletions(-)
diff --git a/policy/ap-pkg-binarypkg.rst b/policy/ap-pkg-binarypkg.rst
index 1499cb1..98bb3cf 100644
--- a/policy/ap-pkg-binarypkg.rst
+++ b/policy/ap-pkg-binarypkg.rst
@@ -121,7 +121,7 @@ Here is a brief list of the control information files supported by
.. _s-pkg-controlfile:
-The main control information file: ``control``
+The binary package control file: ``control``
----------------------------------------------
The most important control information file used by ``dpkg`` when it
diff --git a/policy/ap-pkg-sourcepkg.rst b/policy/ap-pkg-sourcepkg.rst
index 980935e..f1adc6b 100644
--- a/policy/ap-pkg-sourcepkg.rst
+++ b/policy/ap-pkg-sourcepkg.rst
@@ -93,8 +93,8 @@ Sources which build several binaries will typically need something like:
dpkg-gencontrol -Pdebian/pkg -ppackage
The ``-P`` tells ``dpkg-gencontrol`` that the package is being built in
-a non-default directory, and the ``-p`` tells it which package's control
-file should be generated.
+a non-default directory, and the ``-p`` tells it which binary package's
+control file should be generated.
``dpkg-gencontrol`` also adds information to the list of files in
``debian/files``, for the benefit of (for example) a future invocation
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 3678c79..400e664 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -41,8 +41,8 @@ field might be:
the field name is ``Package`` and the field value ``libc6``.
-Empty field values are only permitted in source package control files
-(``debian/control``). Such fields are ignored.
+Empty field values are only permitted in source package template
+control files (``debian/control``). Such fields are ignored.
A stanza must not contain more than one instance of a particular
field name.
@@ -93,8 +93,8 @@ All control files must be encoded in UTF-8.
.. _s-sourcecontrolfiles:
-Source package control files -- ``debian/control``
---------------------------------------------------
+Debian source package template control files -- ``debian/control``
+------------------------------------------------------------------
The ``debian/control`` file contains the most vital (and
version-independent) information about the source package and about the
@@ -106,8 +106,7 @@ binary package that the source tree builds. Each binary package built
from this source package has a corresponding stanza, except for any
automatically-generated debug packages that do not require one.
-The fields in the general stanza (the first one, for the source
-package) are:
+The fields in the source package stanza (the first one) are:
- :ref:`Source <s-f-Source>` (mandatory)
@@ -172,8 +171,8 @@ substituted by ``dpkg-gencontrol``, ``dpkg-genchanges`` or
.. _s-binarycontrolfiles:
-Binary package control files -- ``DEBIAN/control``
---------------------------------------------------
+Debian binary package control files -- ``DEBIAN/control``
+---------------------------------------------------------
The ``DEBIAN/control`` file contains the most vital (and
version-dependent) information about a binary package. It consists of a
@@ -209,8 +208,8 @@ The fields in this file are:
.. _s-debiansourcecontrolfiles:
-Debian source control files -- ``.dsc``
----------------------------------------
+Debian source package control files -- ``.dsc``
+-----------------------------------------------
This file consists of a single stanza, possibly surrounded by an OpenPGP
signature. The fields of that stanza are listed below. Their syntax
@@ -249,15 +248,15 @@ is described above, in :ref:`s-controlsyntax`.
- :ref:`Files <s-f-Files>` (mandatory)
-The Debian source control file is generated by ``dpkg-source`` when it
+The Debian source package control file is generated by ``dpkg-source`` when it
builds the source archive, from other files in the source package,
described above. When unpacking, it is checked against the files and
directories in the other parts of the source package.
.. _s-debianchangesfiles:
-Debian changes files -- ``.changes``
-------------------------------------
+Debian upload changes control files -- ``.changes``
+---------------------------------------------------
The ``.changes`` files are used by the Debian archive maintenance
software to process updates to packages. They consist of a single
@@ -452,7 +451,7 @@ other than ``any`` is for the minority of cases where a program is not
portable or is not useful on some architectures. Where possible, the
program should be made portable instead.
-In the Debian source control file ``.dsc``, this field contains a list
+In the Debian source package control file ``.dsc``, this field contains a list
of architectures and architecture wildcards separated by spaces. When
the list contains the architecture wildcard ``any``, the only other
value allowed in the list is ``all``.
@@ -460,7 +459,7 @@ value allowed in the list is ``all``.
The list may include (or consist solely of) the special value ``all``.
In other words, in ``.dsc`` files unlike the ``debian/control``, ``all``
may occur in combination with specific architectures. The
-``Architecture`` field in the Debian source control file ``.dsc`` is
+``Architecture`` field in the Debian source package control file ``.dsc`` is
generally constructed from the ``Architecture`` fields in the
``debian/control`` in the source package.
@@ -500,8 +499,8 @@ the architecture for the build process.
~~~~~~~~~~~~~
This is a boolean field which may occur only in the control file of a
-binary package or in a per-package fields stanza of a source package
-control file.
+binary package or in a binay package stanza of a source package
+template control file.
If set to ``yes`` then the package management system will refuse to
remove the package (upgrading and replacing it is still possible). The
@@ -773,10 +772,10 @@ This list of version conventions is not exhaustive.
``Description``
~~~~~~~~~~~~~~~
-In a source or binary control file, the ``Description`` field contains a
-description of the binary package, consisting of two parts, the synopsis
-or the short description, and the long description. It is a multiline
-field with the following format:
+In a source template control file or binary control file, the ``Description``
+field contains a description of the binary package, consisting of two parts,
+the synopsis or the short description, and the long description. It is a
+multiline field with the following format:
.. code-block:: debcontrol
@@ -934,7 +933,7 @@ packages being uploaded, separated by whitespace (not commas).
``Installed-Size``
~~~~~~~~~~~~~~~~~~
-This field appears in the control files of binary packages, and in the
+This field appears in the binary package control files, and in the
``Packages`` files. It gives an estimate of the total amount of disk
space required to install the named package. Actual installed size may
vary based on block size, file system properties, or actions taken by
@@ -983,7 +982,7 @@ filename. For example:
7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
The :ref:`section <s-f-Section>` and :ref:`priority <s-f-Priority>` are the
-values of the corresponding fields in the main source control file. If
+values of the corresponding fields in the source template control file. If
no section or priority is specified then ``-`` should be used, though
section and priority values must be specified for new packages to be
installed properly.
@@ -1154,8 +1153,8 @@ field for a list of package types.
Simple field containing a word indicating the type of package: ``deb``
for binary packages and ``udeb`` for micro binary packages. Other types
-not defined here may be indicated. In source package control files, the
-``Package-Type`` field should be omitted instead of giving it a value of
+not defined here may be indicated. In source package template control files,
+the ``Package-Type`` field should be omitted instead of giving it a value of
``deb``, as this value is assumed for stanzas lacking this field.
.. _s-f-Dgit:
@@ -1185,7 +1184,7 @@ execution environments to discover packages which provide tests.
This field is automatically added to Debian source control files
(``.dsc``) by ``dpkg``, with the value ``autopkgtest``, when a
``debian/tests/control`` file is present in the source package. This
-field may also be used in source package control files
+field may also be used in source package template control files
(``debian/control``) if needed in other situations.
.. _s-f-Rules-Requires-Root:
@@ -1304,9 +1303,10 @@ defines and when they are needed.
User-defined fields
-------------------
-Additional user-defined fields may be added to the source package
+Additional user-defined fields may be added to the source package template
control file. Such fields will be ignored, and not copied to (for
-example) binary or Debian source control files or upload control files.
+example) binary or Debian source control files or
+Debian upload changes control files.
If you wish to add additional unsupported fields to these output files
you should use the mechanism described here.
@@ -1317,9 +1317,9 @@ Fields in the main source control information file with names starting
name after the hyphen will be used in the output file. Where the letter
``B`` is used the field will appear in binary package control files,
where the letter ``S`` is used in Debian source control files and where
-``C`` is used in upload control (``.changes``) files.
+``C`` is used in Debian upload changes control files.
-For example, if the main source information control file contains the
+For example, if the source package template control file contains the
field
.. code-block:: debcontrol
diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index c18050f..a7a68ff 100644
--- a/policy/ch-relationships.rst
+++ b/policy/ch-relationships.rst
@@ -31,7 +31,7 @@ which only ``=`` is allowed. [#]_
Whitespace may appear at any point in the version specification subject
to the rules in :ref:`s-controlsyntax`, and must appear
where it's necessary to disambiguate; it is not otherwise significant.
-All of the relationship fields can only be folded in source package
+All of the relationship fields can only be folded in source package template
control files. For consistency and in case of future changes to ``dpkg``
it is recommended that a single space be used after a version
relationship and before a version number; it is also conventional to put
@@ -87,7 +87,7 @@ separated by spaces:
For binary relationship fields and the ``Built-Using`` field, the
architecture restriction syntax is only supported in the source package
-control file ``debian/control``. When the corresponding binary package
+template control file ``debian/control``. When the corresponding binary package
control file is generated, the relationship will either be omitted or
included without the architecture restriction based on the architecture
of the binary package. This means that architecture restrictions must
@@ -132,9 +132,9 @@ cpu, ``bar`` on architectures using any kernel and an i386 cpu, and
``baz`` on any architecture using a kernel other than Linux.
Note that the binary package relationship fields such as ``Depends``
-appear in one of the binary package stanzas of the control file,
+appear in one of the binary package stanzas of the template control file,
whereas the build-time relationships such as ``Build-Depends`` appear in
-the source package stanza of the control file (which is the first
+the source package stanza of the template control file (which is the first
section).
.. _s-binarydeps:
--
2.39.0
From a2bae6b39339d68c7dd4b8e23fc8cf7f1429ce38 Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@debian.org>
Date: Sat, 17 Dec 2022 13:12:05 +0100
Subject: [PATCH 6/6] =?UTF-8?q?Use=20=C2=ABpackage=20metadata=C2=BB=20inst?=
=?UTF-8?q?ead=20of=20=C2=ABcontrol=20information=C2=BB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Using «control information» when talking about control files and control
formats, and similar gets confusing fast. Switch to package metadata, as
some of the files in the deb(5) archive control member are not usually
in deb822(5) format.
---
policy/ap-pkg-binarypkg.rst | 15 +++++++--------
policy/ap-pkg-conffiles.rst | 2 +-
policy/ap-pkg-sourcepkg.rst | 2 +-
policy/ch-binary.rst | 14 +++++++-------
policy/ch-controlfields.rst | 2 +-
policy/ch-maintainerscripts.rst | 6 +++---
6 files changed, 20 insertions(+), 21 deletions(-)
diff --git a/policy/ap-pkg-binarypkg.rst b/policy/ap-pkg-binarypkg.rst
index 98bb3cf..355f777 100644
--- a/policy/ap-pkg-binarypkg.rst
+++ b/policy/ap-pkg-binarypkg.rst
@@ -65,20 +65,19 @@ To view the copyright file for a package you could use this command:
.. _s-pkg-controlarea:
-Package control information files
----------------------------------
+Binary package metadata files
+-----------------------------
-The control information portion of a binary package is a collection of
+The package metadata portion of a binary package is a collection of
files with names known to ``dpkg``. It will treat the contents of these
files specially - some of them contain information used by ``dpkg`` when
installing or removing the package; others are scripts which the package
maintainer wants ``dpkg`` to run.
-It is possible to put other files in the package control information
-file area, but this is not generally a good idea (though they will
-largely be ignored).
+It is possible to put other files in the package metadata archive member,
+but this is not generally a good idea (though they will largely be ignored).
-Here is a brief list of the control information files supported by
+Here is a brief list of the package metadata files supported by
``dpkg`` and a summary of what they're used for.
``control``
@@ -124,7 +123,7 @@ Here is a brief list of the control information files supported by
The binary package control file: ``control``
----------------------------------------------
-The most important control information file used by ``dpkg`` when it
+The most important package metadata file used by ``dpkg`` when it
installs a package is ``control``. It contains all the package's "vital
statistics".
diff --git a/policy/ap-pkg-conffiles.rst b/policy/ap-pkg-conffiles.rst
index 81b9fa1..ad02321 100644
--- a/policy/ap-pkg-conffiles.rst
+++ b/policy/ap-pkg-conffiles.rst
@@ -25,7 +25,7 @@ each system.
Automatic handling of configuration files by ``dpkg``
-----------------------------------------------------
-A package may contain a control information file called ``conffiles``.
+A binary package may contain a package metadata file called ``conffiles``.
This file should be a list of filenames of configuration files needing
automatic handling, separated by newlines. The filenames should be
absolute pathnames, and the files referred to should actually exist in
diff --git a/policy/ap-pkg-sourcepkg.rst b/policy/ap-pkg-sourcepkg.rst
index f1adc6b..c296d37 100644
--- a/policy/ap-pkg-sourcepkg.rst
+++ b/policy/ap-pkg-sourcepkg.rst
@@ -160,7 +160,7 @@ The Debian package source tree
------------------------------
The source archive scheme described later is intended to allow a Debian
-package source tree with some associated control information to be
+package source tree with some associated package metadata to be
reproduced and transported easily. The Debian package source tree is a
version of the original program with certain files added for the benefit
of the packaging process, and with any other changes required made to
diff --git a/policy/ch-binary.rst b/policy/ch-binary.rst
index e517f26..5739dc5 100644
--- a/policy/ch-binary.rst
+++ b/policy/ch-binary.rst
@@ -9,10 +9,10 @@ A ``.deb`` package contains two sets of files: a set of files to install
on the system when the package is installed, and a set of files that
provide additional metadata about the package or which are executed when
the package is installed or removed. This second set of files is called
-*control information files*. Among those files are the package maintainer
+*package metadata files*. Among those files are the package maintainer
scripts and ``control``, the :ref:`binary package control file
<s-binarycontrolfiles>` that contains the control fields for the
-package. Other control information files include :ref:`symbols
+package. Other package metadata files include :ref:`symbols
<s-sharedlibs-symbols>` or :ref:`shlibs <s-sharedlibs-shlibdeps>` used to
store shared library dependency information and the ``conffiles`` file
that lists the package's configuration files (described in
@@ -23,10 +23,10 @@ information files and files in the Debian control file format.
Throughout this document, a *control file* refers to a file in the
Debian control file format. These files are documented in
:doc:`Control files and their fields <ch-controlfields>`. Only files
-referred to specifically as *control information files* are the files
-included in the control information file member of the ``.deb`` file
-format used by binary packages. Most control information files are not
-in the Debian control file format.
+referred to specifically as *package metadata files* are the files
+included in the package metadata member (called ``control.tar``) of the
+``.deb`` file format used by binary packages. Most package metadata files
+are not in the Debian control file format.
.. _s3.1:
@@ -391,7 +391,7 @@ available from the Debian web mirrors at
https://www.debian.org/doc/packaging-manuals/debconf_specification.html.
Packages which use the Debian Configuration Management Specification may
-contain the additional control information files ``config`` and
+contain the additional package metadata files ``config`` and
``templates``. ``config`` is an additional maintainer script used for
package configuration, and ``templates`` contains templates used for
user prompting. The ``config`` script might be run before the
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 400e664..42d482a 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -1311,7 +1311,7 @@ Debian upload changes control files.
If you wish to add additional unsupported fields to these output files
you should use the mechanism described here.
-Fields in the main source control information file with names starting
+Fields in the source package template control file with names starting
``X``, followed by one or more of the letters ``BCS`` and a hyphen
``-``, will be copied to the output files. Only the part of the field
name after the hyphen will be used in the output file. Where the letter
diff --git a/policy/ch-maintainerscripts.rst b/policy/ch-maintainerscripts.rst
index 724074c..118e00c 100644
--- a/policy/ch-maintainerscripts.rst
+++ b/policy/ch-maintainerscripts.rst
@@ -10,7 +10,7 @@ It is possible to supply scripts as part of a package which the package
management system will run for you when your package is installed,
upgraded or removed.
-These scripts are the control information files ``preinst``,
+These scripts are the package metadata files ``preinst``,
``postinst``, ``prerm`` and ``postrm``. They must be proper executable
files; if they are scripts (which is recommended), they must start with
the usual ``#!`` convention. They should be readable and executable by
@@ -25,8 +25,8 @@ It is also important, of course, that they exit with a zero status if
everything went well.
Additionally, packages interacting with users using ``debconf`` in the
-``postinst`` script should install a ``config`` script as a control
-information file. See :ref:`s-maintscriptprompt` for
+``postinst`` script should install a ``config`` script as a package
+metadata file. See :ref:`s-maintscriptprompt` for
details.
When a package is upgraded a combination of the scripts from the old and
--
2.39.0
Reply to: