This is an automated email from the git hooks/post-receive script. guillem pushed a commit to branch main in repository dpkg.
View the commit online: https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=b3bb15c52389a5f24689887a2f8b39e1b1408916 commit b3bb15c52389a5f24689887a2f8b39e1b1408916 Author: Guillem Jover <[email protected]> AuthorDate: Tue Dec 12 23:58:35 2023 +0100 doc, man: Clarify terminology for Debian control files Their current descriptive names are very close and easily confused if one is not paying close attention. Use new terminology that tries to make them less ambiguous and more 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» --- man/deb-changes.pod | 2 +- man/deb-control.pod | 9 +++++---- man/deb-src-control.pod | 11 +++++++---- man/dsc.pod | 2 +- scripts/Dpkg/Control.pm | 18 +++++++++--------- scripts/Dpkg/Control/Types.pm | 4 ++-- 6 files changed, 25 insertions(+), 21 deletions(-) diff --git a/man/deb-changes.pod b/man/deb-changes.pod index 5d83f5ccc..282d3396a 100644 --- a/man/deb-changes.pod +++ b/man/deb-changes.pod @@ -21,7 +21,7 @@ =head1 NAME -deb-changes - Debian changes file format +deb-changes - Debian upload changes control file format =head1 SYNOPSIS diff --git a/man/deb-control.pod b/man/deb-control.pod index 370508cc2..6f72e2ba9 100644 --- a/man/deb-control.pod +++ b/man/deb-control.pod @@ -23,7 +23,7 @@ =head1 NAME -deb-control - Debian binary packages' master control file format +deb-control - Debian binary package control file format =head1 SYNOPSIS @@ -32,8 +32,9 @@ B<DEBIAN/control> =head1 DESCRIPTION Each Debian binary package contains a B<control> file in its B<control> -member, and its L<deb822(5)> format is a subset of the master -B<debian/control> file in Debian source packages, see L<deb-src-control(5)>. +member, and its L<deb822(5)> format is a subset of the B<debian/control> +template source control file in Debian source packages, +see L<deb-src-control(5)>. This file contains a number of fields. Each field begins with a tag, such as @@ -417,7 +418,7 @@ B<.buildinfo> file, which supersedes it. This field specifies a whitespace separated list of reasons why this package was auto-generated. Binary packages marked with this field will not appear in the -I<debian/control> master source control file. +I<debian/control> template source control file. The only currently used reason is B<debug-symbols>. =item B<Build-Ids:> I<elf-build-id-list> diff --git a/man/deb-src-control.pod b/man/deb-src-control.pod index 4342aaa08..65dd027d4 100644 --- a/man/deb-src-control.pod +++ b/man/deb-src-control.pod @@ -21,7 +21,7 @@ =head1 NAME -deb-src-control - Debian source packages' master control file format +deb-src-control - Debian source package template control file format =head1 SYNOPSIS @@ -29,13 +29,16 @@ B<debian/control> =head1 DESCRIPTION -Each Debian source package contains the master «B<debian/control>» file, +Each Debian source package contains the «B<debian/control>» template source +control file, and its L<deb822(5)> format is a superset of the B<control> file shipped in Debian binary packages, see L<deb-control(5)>. This file contains at least 2 stanzas, separated by a blank line. -The first stanza lists all information about the source package in general, -while each following stanza describes exactly one binary package. +The first stanza is called the source package stanza and lists all +information about the source package in general, +while each following stanzas are called the binary package stanzas and +describe exactly one binary package per stanza. Each stanza consists of at least one field. A field starts with a field name, such as B<Package> or B<Section> (case insensitive), followed by a colon, the body of the field diff --git a/man/dsc.pod b/man/dsc.pod index ea59ffedb..9e6f91624 100644 --- a/man/dsc.pod +++ b/man/dsc.pod @@ -20,7 +20,7 @@ =head1 NAME -dsc - Debian source packages' control file format +dsc - Debian source package control file format =head1 SYNOPSIS diff --git a/scripts/Dpkg/Control.pm b/scripts/Dpkg/Control.pm index b41a4ea97..6305d4bf6 100644 --- a/scripts/Dpkg/Control.pm +++ b/scripts/Dpkg/Control.pm @@ -38,12 +38,12 @@ information is not yet known. =item CTRL_INFO_SRC -Corresponds to the first stanza in a F<debian/control> file in +Corresponds to the first source package stanza in a F<debian/control> file in a Debian source package. =item CTRL_INFO_PKG -Corresponds to subsequent stanza in a F<debian/control> file +Corresponds to subsequent binary package stanza in a F<debian/control> file in a Debian source package. =item CTRL_REPO_RELEASE @@ -106,7 +106,7 @@ machine readable format. =item CTRL_TESTS -Corresponds to a package tests control file in F<debian/tests/control>. +Corresponds to a source package tests control file in F<debian/tests/control>. =back @@ -193,9 +193,9 @@ sub set_options { $$self->{allow_pgp} = ($t & (CTRL_PKG_SRC | CTRL_FILE_CHANGES | CTRL_REPO_RELEASE)) ? 1 : 0; $$self->{drop_empty} = ($t & (CTRL_INFO_PKG | CTRL_INFO_SRC)) ? 0 : 1; if ($t == CTRL_INFO_SRC) { - $$self->{name} = g_('general section of control info file'); + $$self->{name} = g_('source package stanza of template control file'); } elsif ($t == CTRL_INFO_PKG) { - $$self->{name} = g_("package's section of control info file"); + $$self->{name} = g_('binary package stanza of template control file'); } elsif ($t == CTRL_CHANGELOG) { $$self->{name} = g_('parsed version of changelog'); } elsif ($t == CTRL_COPYRIGHT_HEADER) { @@ -205,7 +205,7 @@ sub set_options { } elsif ($t == CTRL_COPYRIGHT_HEADER) { $$self->{name} = g_('license stanza of copyright file'); } elsif ($t == CTRL_TESTS) { - $$self->{name} = g_("package's tests control file"); + $$self->{name} = g_('source package tests control file'); } elsif ($t == CTRL_REPO_RELEASE) { $$self->{name} = sprintf(g_("repository's %s file"), 'Release'); } elsif ($t == CTRL_INDEX_SRC) { @@ -213,13 +213,13 @@ sub set_options { } elsif ($t == CTRL_INDEX_PKG) { $$self->{name} = sprintf(g_("stanza in repository's %s file"), 'Packages'); } elsif ($t == CTRL_PKG_SRC) { - $$self->{name} = sprintf(g_('%s file'), '.dsc'); + $$self->{name} = g_('source package control file'); } elsif ($t == CTRL_PKG_DEB) { - $$self->{name} = g_('control info of a .deb package'); + $$self->{name} = g_('binary package control file'); } elsif ($t == CTRL_FILE_BUILDINFO) { $$self->{name} = g_('build information file'); } elsif ($t == CTRL_FILE_CHANGES) { - $$self->{name} = sprintf(g_('%s file'), '.changes'); + $$self->{name} = g_('upload changes control file'); } elsif ($t == CTRL_FILE_VENDOR) { $$self->{name} = g_('vendor file'); } elsif ($t == CTRL_FILE_STATUS) { diff --git a/scripts/Dpkg/Control/Types.pm b/scripts/Dpkg/Control/Types.pm index 89d0cebe1..a3139c6fe 100644 --- a/scripts/Dpkg/Control/Types.pm +++ b/scripts/Dpkg/Control/Types.pm @@ -58,9 +58,9 @@ use Exporter qw(import); use constant { CTRL_UNKNOWN => 0, - # First control stanza in debian/control. + # First source package control stanza in debian/control. CTRL_INFO_SRC => 1 << 0, - # Subsequent control stanza in debian/control. + # Subsequent binary package control stanza in debian/control. CTRL_INFO_PKG => 1 << 1, # Entry in repository's Sources files. CTRL_INDEX_SRC => 1 << 2, -- Dpkg.Org's dpkg
