Hi!
On Sun, 2022-09-18 at 17:34:57 -0700, Russ Allbery wrote:
> Sean Whitton <spwhit...@spwhitton.name> writes:
> > On Mon 19 Sep 2022 at 12:45AM +02, Guillem Jover wrote:
> >> So, personally, I'd be happy to fully switch to stanza TBH, because it
> >> seems more specific to our use, probably easier to search for, and
> >> it's shorter.
>
> > I think this is fine for Policy to do.
>
> I vote for switching to stanza. Paragraph is going to be confusing when
> talking about package descriptions, which often have multiple paragraphs
> in the normal English meaning of the term.
Ok, I've prepared the attached incremental patch, which only switches
from paragraph(s) to stanza(s) all over the place.
I've updated all the specs for consistency. I've updated the footnote
to swap the preference and to mention paragraph is now discouraged
nomenclature. I've also updated all «id»s out of consistency, which
might break links, so I can revert that if you'd prefer. And I've
preserved the (upper) casing for one of the titles (“Stand-alone
License Stanza”, although that was not consistent with the other
titles, such as “Files stanza”, I'm happy to lower case that one).
I've gone one by one, but please review carefully as I might have
perhaps switched in excess!
Thanks,
Guillem
From 6d02f28eb1f0cd2f7afa75b04691265425122366 Mon Sep 17 00:00:00 2001
From: Guillem Jover <guil...@debian.org>
Date: Mon, 19 Sep 2022 22:33:40 +0200
Subject: [PATCH] Use stanza to refer to deb822 parts instead of paragraph
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The «stanza» name is a commonly used and understood term when referring
to deb822 blocks. Although «paragraph» is commonly used it has the
problem of being confusing as it then makes it hard to distinguish
actual text paragraphs in prose, while «stanza» is a very specific
term that is not applied anywhere else in the deb822 context, so it's
always more clear and specific.
In addition «stanza» is shorter, which is always a nice attribute
on code for example.
The references in dpkg documentation and code, will be updated shortly,
so that there is uniform nomenclature used.
Fixes: #1020248
---
autopkgtest.md | 2 +-
copyright-format-1.0.xml | 116 ++++++++++++++++-----------------
policy/ch-controlfields.rst | 46 ++++++-------
policy/upgrading-checklist.rst | 8 +--
4 files changed, 87 insertions(+), 85 deletions(-)
diff --git a/autopkgtest.md b/autopkgtest.md
index bc7bdaf..74d6885 100644
--- a/autopkgtest.md
+++ b/autopkgtest.md
@@ -219,7 +219,7 @@ debian/control by adding
XS-Testsuite: autopkgtest
-in the `Source:` paragraph.
+in the `Source:` stanza.
Implicit test control file for known package types
--------------------------------------------------
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index d5d2bbe..954a65b 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -115,17 +115,17 @@
The syntax of the file is the same as for other Debian control files, as
specified in the Debian Policy Manual. See its <ulink
url="https://www.debian.org/doc/debian-policy/ch-controlfields#s-controlsyntax";>section
- 5.1</ulink> for details. Extra fields can be added to any paragraph. No
+ 5.1</ulink> for details. Extra fields can be added to any stanza. No
prefixing is necessary or desired, but please avoid names similar to
standard ones so that mistakes are easier to catch. Future versions of
the <filename>debian/copyright</filename> specification will attempt to
avoid conflicting specifications for widely used extra fields.
</para>
<para>
- The file consists of two or more paragraphs. At minimum, the file
- must include one <link linkend="header-paragraph">header
- paragraph</link> and one <link linkend="files-paragraph">Files
- paragraph</link>.
+ The file consists of two or more stanzas. At minimum, the file
+ must include one <link linkend="header-stanza">header
+ stanza</link> and one <link linkend="files-stanza">Files
+ stanza</link>.
</para>
<para>
There are four types of fields. The definition for each field in this
@@ -184,22 +184,22 @@
</section>
</section>
- <section id="paragraphs">
- <title>Paragraphs</title>
+ <section id="stanzas">
+ <title>Stanzas</title>
<para>
- There are three kinds of paragraphs. The first paragraph in the file
- is called the <link linkend="header-paragraph">header paragraph</link>.
- Every other paragraph is either a <link
- linkend="files-paragraph">Files paragraph</link> or a <link
- linkend="stand-alone-license-paragraph">stand-alone License
- paragraph</link>. This is similar to source and binary package
- paragraphs in <filename>debian/control</filename> files.
+ There are three kinds of stanzas. The first stanza in the file
+ is called the <link linkend="header-stanza">header stanza</link>.
+ Every other stanza is either a <link
+ linkend="files-stanza">Files stanza</link> or a <link
+ linkend="stand-alone-license-stanza">stand-alone License
+ stanza</link>. This is similar to source and binary package
+ stanzas in <filename>debian/control</filename> files.
</para>
- <section id="header-paragraph">
- <title>Header paragraph (once)</title>
+ <section id="header-stanza">
+ <title>Header stanza (once)</title>
<para>
- The following fields may be present in a header paragraph.
+ The following fields may be present in a header stanza.
</para>
<itemizedlist>
<listitem>
@@ -249,9 +249,9 @@
</itemizedlist>
<para>
The <varname>Copyright</varname> and <varname>License</varname>
- fields in the <emphasis>header paragraph</emphasis> may complement
+ fields in the <emphasis>header stanza</emphasis> may complement
but do not replace the fields in the <emphasis>Files
- paragraphs</emphasis>. If present, they summarise the copyright
+ stanzas</emphasis>. If present, they summarise the copyright
notices or redistribution terms for the package as a whole.
</para>
<para>
@@ -264,12 +264,12 @@
</para>
<para>
It is valid to use <varname>License</varname> in the header
- paragraph without an accompanying <varname>Copyright</varname>
+ stanza without an accompanying <varname>Copyright</varname>
field, but <varname>Copyright</varname> alone is not sufficient.
</para>
- <section id="example-header-paragraph">
- <title>Example header paragraph</title>
+ <section id="example-header-stanza">
+ <title>Example header stanza</title>
<programlisting>Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Source: https://www.example.com/software/project
Upstream-Name: SOFTware
@@ -277,18 +277,18 @@ Upstream-Contact: John Doe <john....@example.com></programlisting>
</section>
</section>
- <section id="files-paragraph">
- <title>Files paragraph (repeatable)</title>
+ <section id="files-stanza">
+ <title>Files stanza (repeatable)</title>
<para>
The declaration of copyright and license for files may consist of
- one or more paragraphs. In the simplest case, a single paragraph
+ one or more stanzas. In the simplest case, a single stanza
with <literal>Files: *</literal> can be used to state the license
and copyright for the whole package. Only the license and
copyright information required by the Debian archive is required
to be listed here.
</para>
<para>
- The following fields may be present in a Files paragraph.
+ The following fields may be present in a Files stanza.
</para>
<itemizedlist>
@@ -314,8 +314,8 @@ Upstream-Contact: John Doe <john....@example.com></programlisting>
</listitem>
</itemizedlist>
- <section id="example-files-paragraph">
- <title>Example files paragraphs</title>
+ <section id="example-files-stanza">
+ <title>Example files stanzas</title>
<programlisting>Files:
*
Copyright: 1975-2010 Ulla Upstream
@@ -346,22 +346,22 @@ License: GPL-2+</programlisting>
</para>
<para>
Since the license of the manual pages is the same as most other
- files in the package, the final paragraph above could instead be
- combined with the first paragraph, listing both copyright
+ files in the package, the final stanza above could instead be
+ combined with the first stanza, listing both copyright
statements in one <varname>Copyright</varname> field. Whether to
- combine paragraphs with the same grant of license is left to the
+ combine stanzas with the same grant of license is left to the
discretion of the author of the
<filename>debian/copyright</filename> file.
</para>
</section>
</section>
- <section id="stand-alone-license-paragraph">
- <title>Stand-alone License Paragraph (optional, repeatable)</title>
+ <section id="stand-alone-license-stanza">
+ <title>Stand-alone License Stanza (optional, repeatable)</title>
<para>
- Stand-alone <varname>License</varname> paragraphs can be used to
+ Stand-alone <varname>License</varname> stanzas can be used to
provide the full license text for a given license once, instead of
- repeating it in each <varname>Files</varname> paragraph that refers
+ repeating it in each <varname>Files</varname> stanza that refers
to it.
</para>
<para>
@@ -371,7 +371,7 @@ License: GPL-2+</programlisting>
</para>
<para>
The following fields may be present in a stand-alone License
- paragraph.
+ stanza.
</para>
<itemizedlist>
@@ -504,16 +504,16 @@ License: MPL-1.1
Formatted text, with synopsis.
</para>
<para>
- In the <link linkend="header-paragraph">header paragraph</link>,
+ In the <link linkend="header-stanza">header stanza</link>,
this field gives the license information for the package as a
whole, which may be different or simplified from a combination of
all the per-file license information. In a <link
- linkend="files-paragraph">Files paragraph</link>, this field gives
+ linkend="files-stanza">Files stanza</link>, this field gives
the licensing terms for the files listed in the
- <varname>Files</varname> field for this paragraph. In a <link
- linkend="stand-alone-license-paragraph">stand-alone License
- paragraph</link>, it gives the licensing terms for those
- paragraphs which reference it.
+ <varname>Files</varname> field for this stanza. In a <link
+ linkend="stand-alone-license-stanza">stand-alone License
+ stanza</link>, it gives the licensing terms for those
+ stanzas which reference it.
</para>
<para>
First line (synopsis): an abbreviated name for the license, or
@@ -528,8 +528,8 @@ License: MPL-1.1
If there are no remaining lines, then all of the short names or
short names followed by license exceptions in the synopsis must be
described in <link
- linkend="stand-alone-license-paragraph">stand-alone License
- paragraphs</link>. Otherwise, this field should either include the
+ linkend="stand-alone-license-stanza">stand-alone License
+ stanzas</link>. Otherwise, this field should either include the
full text of the license(s) or include a pointer to the license
file under <filename>/usr/share/common-licenses</filename>. This
field should include all text needed in order to fulfill both
@@ -547,10 +547,10 @@ License: MPL-1.1
Formatted text, no synopsis: one or more free-form copyright
statements. Any formatting is permitted; see the examples below
for some ideas for how to structure the field to make it easier to
- read. In the header paragraph, this field gives the copyright
+ read. In the header stanza, this field gives the copyright
information for the package as a whole, which may be different or
simplified from a combination of all the per-file copyright
- information. In the Files paragraphs, it gives the copyright
+ information. In the Files stanzas, it gives the copyright
information that applies to the files matched by the
<varname>Files</varname> pattern. If a work has no copyright holder
(i.e., it is in the public domain), that information should be
@@ -558,7 +558,7 @@ License: MPL-1.1
</para>
<para>
The <varname>Copyright</varname> field collects all relevant
- copyright notices for the files of this paragraph. Not all
+ copyright notices for the files of this stanza. Not all
copyright notices may apply to every individual file, and years of
publication for one copyright holder may be gathered together. For
example, if file A has:
@@ -566,8 +566,8 @@ License: MPL-1.1
Copyright 2009 Angela Watts</programlisting>
and file B has:
<programlisting>Copyright 2010 Angela Watts</programlisting>
- a single paragraph may still be used for both files. The
- <varname>Copyright</varname> field for that paragraph would
+ a single stanza may still be used for both files. The
+ <varname>Copyright</varname> field for that stanza would
contain:
<programlisting>Copyright 2008 John Smith
Copyright 2009, 2010 Angela Watts</programlisting>
@@ -586,7 +586,7 @@ Copyright 2009, 2010 Angela Watts</programlisting>
<title><varname>Files</varname></title>
<para>
Whitespace-separated list: list of patterns indicating files covered
- by the license and copyright specified in this paragraph.
+ by the license and copyright specified in this stanza.
</para>
<para>
Filename patterns in the <varname>Files</varname> field are
@@ -656,14 +656,14 @@ Copyright 2009, 2010 Angela Watts</programlisting>
recognized.
</para>
<para>
- Multiple <varname>Files</varname> paragraphs are allowed. The last
- paragraph that matches a particular file applies to it. More
- general paragraphs should therefore be given first, followed by
+ Multiple <varname>Files</varname> stanzas are allowed. The last
+ stanza that matches a particular file applies to it. More
+ general stanzas should therefore be given first, followed by
more specific overrides.
</para>
<para>
Exclusions are only supported by adding <varname>Files</varname>
- paragraphs to override the previous match.
+ stanzas to override the previous match.
</para>
<para>
This syntax does not distinguish file names from directory
@@ -713,8 +713,8 @@ Copyright 2009, 2010 Angela Watts</programlisting>
<filename>debian/copyright</filename>, nor any requirements in the
license of the work regarding reproduction of legal notices. This
information must still be included in the <varname>License</varname>
- field, either in a stand-alone License paragraph or in the relevant
- files paragraph.
+ field, either in a stand-alone License stanza or in the relevant
+ files stanza.
</para>
<para>
For licenses that have multiple versions in use, the short name is
@@ -1157,10 +1157,10 @@ also delete it here.</programlisting>
on public domain</ulink> is a useful reference for this subject.
</para>
<para>
- When the <varname>License</varname> field in a paragraph has the
+ When the <varname>License</varname> field in a stanza has the
short name <literal>public-domain</literal>, the remaining lines of
the field <emphasis>must</emphasis> explain exactly what exemption
- the corresponding files for that paragraph have from default
+ the corresponding files for that stanza have from default
copyright restrictions.
</para>
</section>
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 428b8a7..a392213 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -11,17 +11,17 @@ files which control the installation of uploaded files. [#]_
Syntax of control files
-----------------------
-A control file consists of one or more paragraphs of fields. [#]_ The
-paragraphs are separated by empty lines. Parsers may accept lines
-consisting solely of spaces and tabs as paragraph separators, but
+A control file consists of one or more stanzas of fields. [#]_ The
+stanzas are separated by empty lines. Parsers may accept lines
+consisting solely of spaces and tabs as stanza separators, but
control files should use empty lines. Some control files allow only one
-paragraph; others allow several, in which case each paragraph usually
+stanza; others allow several, in which case each stanza usually
refers to a different package. (For example, in source packages, the
-first paragraph refers to the source package, and later paragraphs refer
+first stanza refers to the source package, and later stanzas refer
to binary packages generated from the source.) The ordering of the
-paragraphs in control files is significant.
+stanzas in control files is significant.
-Each paragraph consists of a series of data fields. Each field consists
+Each stanza consists of a series of data fields. Each field consists
of the field name followed by a colon and then the data/value associated
with that field. The field name is composed of US-ASCII characters
excluding control characters, space, and colon (i.e., characters in the
@@ -44,7 +44,7 @@ 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.
-A paragraph must not contain more than one instance of a particular
+A stanza must not contain more than one instance of a particular
field name.
There are three types of fields:
@@ -79,7 +79,7 @@ Field names are not case-sensitive, but it is usual to capitalize the
field names using mixed case as shown below. Field values are
case-sensitive unless the description of the field says otherwise.
-Paragraph separators (empty lines), and lines consisting only of U+0020
+Stanza separators (empty lines), and lines consisting only of U+0020
SPACE and U+0009 TAB, are not allowed within field values or between
fields. Empty lines in field values are usually escaped by representing
them by a U+0020 SPACE followed by a U+002E (``.``).
@@ -100,13 +100,13 @@ The ``debian/control`` file contains the most vital (and
version-independent) information about the source package and about the
binary packages it creates.
-The first paragraph of the control file contains information about the
-source package in general. The subsequent paragraphs each describe a
+The first stanza of the control file contains information about the
+source package in general. The subsequent stanzas each describe a
binary package that the source tree builds. Each binary package built
-from this source package has a corresponding paragraph, except for any
+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 paragraph (the first one, for the source
+The fields in the general stanza (the first one, for the source
package) are:
- :ref:`Source <s-f-Source>` (mandatory)
@@ -131,7 +131,7 @@ package) are:
- :ref:`Rules-Requires-Root <s-f-Rules-Requires-Root>`
-The fields in the binary package paragraphs are:
+The fields in the binary package stanzas are:
- :ref:`Package <s-f-Package>` (mandatory)
@@ -177,7 +177,7 @@ 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
-single paragraph.
+single stanza.
The fields in this file are:
@@ -212,8 +212,8 @@ The fields in this file are:
Debian source control files -- ``.dsc``
---------------------------------------
-This file consists of a single paragraph, possibly surrounded by an OpenPGP
-signature. The fields of that paragraph are listed below. Their syntax
+This file consists of a single stanza, possibly surrounded by an OpenPGP
+signature. The fields of that stanza are listed below. Their syntax
is described above, in :ref:`s-controlsyntax`.
- :ref:`Format <s-f-Format>` (mandatory)
@@ -261,7 +261,7 @@ Debian changes files -- ``.changes``
The ``.changes`` files are used by the Debian archive maintenance
software to process updates to packages. They consist of a single
-paragraph, possibly surrounded by an OpenPGP signature. That paragraph
+stanza, possibly surrounded by an OpenPGP signature. That stanza
contains information from the ``debian/control`` file and other data
about the source package gathered via ``debian/changelog`` and
``debian/rules``.
@@ -500,7 +500,7 @@ 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 paragraph of a source package
+binary package or in a per-package fields stanza of a source package
control file.
If set to ``yes`` then the package management system will refuse to
@@ -1153,7 +1153,7 @@ 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
-``deb``, as this value is assumed for paragraphs lacking this field.
+``deb``, as this value is assumed for stanzas lacking this field.
.. _s-f-Dgit:
@@ -1353,11 +1353,13 @@ details.
``dpkg``'s internal databases are in a similar format.
.. [#]
- The paragraphs are also sometimes referred to as stanzas.
+ The stanzas somtimes used to be referred to as paragraphs, but that
+ caused confusion with text paragraphs in prose, so it is now considered
+ a discouraged term.
.. [#]
This folding method is similar to RFC 5322, allowing control files
- that contain only one paragraph and no multiline fields to be read by
+ that contain only one stanza and no multiline fields to be read by
parsers written for RFC 5322.
.. [#]
diff --git a/policy/upgrading-checklist.rst b/policy/upgrading-checklist.rst
index 44ae3b6..45ccc33 100644
--- a/policy/upgrading-checklist.rst
+++ b/policy/upgrading-checklist.rst
@@ -510,7 +510,7 @@ Released May, 2017.
5.2
Automatically-generated debug packages do not need to have a
- corresponding paragraph in ``debian/control``. (This is existing
+ corresponding stanza in ``debian/control``. (This is existing
practice; this Policy update is just clearer about it.)
5.6.12
@@ -890,9 +890,9 @@ Released April, 2011.
are significant.
5.1
- Parsers are allowed to accept paragraph separation lines containing
+ Parsers are allowed to accept stanza separation lines containing
whitespace, but control files should use completely empty lines.
- Ordering of paragraphs is significant. Field names must be composed
+ Ordering of stanzas is significant. Field names must be composed
of printable ASCII characters except colon and must not begin with
#.
@@ -1033,7 +1033,7 @@ Released June, 2010.
Date control field is now precisely specified.
5.1
- A control paragraph must not contain more than one instance of a
+ A control stanza must not contain more than one instance of a
particular field name.
5.4, 5.5, 5.6.24
--
2.37.2
