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

