Package: debian-policy
Version: 4.1.0.0
Severity: minor
Tags: patch
Howdy all,
I have made some minor clarifying changes while working on another bug
report.
These changes do not have any substantive effect on the intended
meaning of the passages, only to clarity of expression.
The output of ‘git request-pull’ for these changes:
=====
The following changes since commit b9684c285afd148b102fc76f566175712cbfacac:
in Testsuite:, add hints to explain some terminology (2017-09-02 08:25:56 -0700)
are available in the git repository at:
bignose@git.debian.org:public_git/debian-full/debian-policy.git wip/maintenance/wording-clarifications
for you to fetch changes up to 1bf68292ff9f8617a79d974a54a9e58372644d3e:
Clarify a potential contradiction in which files have what license. (2017-09-03 14:24:36 +1000)
----------------------------------------------------------------
(from the branch description for wip/maintenance/wording-clarifications local branch)
Clarify and re-word some passages.
----------------------------------------------------------------
Ben Finney (6):
Separate some longer passages into paragraphs.
Link terms to their definitions.
Clarify “makes no sense” by instead stating why it is not acceptable.
Correct reference specifically to fields in a paragraph.
Use tighter phrasing of copyright holders and license grant.
Clarify a potential contradiction in which files have what license.
copyright-format-1.0.xml | 117 ++++++++++++++++++++++++++++-------------------
1 file changed, 69 insertions(+), 48 deletions(-)
=====
--
\ “I have a map of the United States; it's actual size. It says |
`\ ‘1 mile equals 1 mile’. Last summer, I folded it.” —Steven |
_o__) Wright |
Ben Finney <bignose@debian.org>
From 06a043b3c8edf7765d3dc9b469aed8d467e0cfbb Mon Sep 17 00:00:00 2001
From: Ben Finney <bignose@debian.org>
Date: Sun, 3 Sep 2017 14:23:55 +1000
Subject: [PATCH 1/6] Separate some longer passages into paragraphs.
---
copyright-format-1.0.xml | 91 ++++++++++++++++++++++++++++--------------------
1 file changed, 54 insertions(+), 37 deletions(-)
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index 2eef301b..e40a710a 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -167,12 +167,16 @@
<para>
Formatted text fields use the same rules as the long description
in a package's <varname>Description</varname> field in Debian
- control files. In some but not all cases, the first line may have
- special meaning as a synopsis, similar to how the
- <varname>Description</varname> field uses the first line for the
- short description. See Debian Policy's section 5.6.13, <ulink
+ control files.
+ </para>
+ <para>
+ In some but not all cases, the first line may have special
+ meaning as a synopsis, similar to how the
+ <varname>Description</varname> field uses the first line for
+ the short description. See Debian Policy's section 5.6.13,
+ <ulink
url="https://www.debian.org/doc/debian-policy/ch-controlfields#s-f-Description";><quote>Description</quote></ulink>,
- for details. For example, <varname>Disclaimer</varname> is a
+ for details. For example, <varname>Disclaimer</varname> is a
formatted text field that has no special first line, and
<varname>License</varname> is a formatted text field where the
first line indicates the short name or names of the licenses.
@@ -246,16 +250,22 @@
<para>
The <varname>Copyright</varname> and <varname>License</varname>
fields in the <emphasis>header paragraph</emphasis> may complement
- but do not replace the <emphasis>Files paragraphs</emphasis>. If
+ but do not replace the <emphasis>Files paragraphs</emphasis>. If
present, they summarise the copyright notices or redistribution
- terms for the package as a whole. For example, when a work
- combines a permissive and a copyleft license,
- <varname>License</varname> can be used to clarify the license
- terms for the combination. <varname>Copyright</varname> and
- <varname>License</varname> together can also be used to document a
- <emphasis>compilation copyright</emphasis> and license. It is
- possible to use only <varname>License</varname> in the header
- paragraph, but <varname>Copyright</varname> alone makes no sense.
+ terms for the package as a whole.
+ </para>
+ <para>
+ For example, when a work has a grant of license under both a
+ permissive and a copyleft license, <varname>License</varname> can
+ be used to clarify the license terms for the combination.
+ <varname>Copyright</varname> and <varname>License</varname>
+ together can also be used to document a <emphasis>compilation
+ copyright</emphasis> and license.
+ </para>
+ <para>
+ It is valid to use <varname>License</varname> in the header
+ paragraph without an accompanying <varname>Copyright</varname>
+ field, but <varname>Copyright</varname> alone makes no sense.
</para>
<section id="example-header-paragraph">
@@ -320,7 +330,8 @@ License: GPL-3+
Files: */*.1
Copyright: 2010 Manuela Manpager
-License: GPL-2+</programlisting>
+License: GPL-2+
+</programlisting>
<para>
In this example, all files are copyright by the upstream and licensed
under the GPL, version 2 or later, with three exceptions. All the
@@ -346,8 +357,11 @@ License: GPL-2+</programlisting>
<para>
Stand-alone <varname>License</varname> paragraphs 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 to
- it. The first line of the <varname>License</varname> field must be a
+ repeating it in each <varname>Files</varname> paragraph that refers
+ to it.
+ </para>
+ <para>
+ The first line of the <varname>License</varname> field must be a
single license short name or a short name followed by a license
exception.
</para>
@@ -481,32 +495,35 @@ License: MPL-1.1
<section id="license-field">
<title><varname>License</varname></title>
<para>
- Formatted text, with synopsis. In the header paragraph, 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 Files paragraph, this field gives the
- licensing terms for the files listed in the <varname>Files</varname>
- field for this paragraph. In a stand-alone License paragraph, it
- gives the licensing terms for those paragraphs which reference it.
+ Formatted text, with synopsis.
+ </para>
+ <para>
+ In the header paragraph, 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
+ Files paragraph, this field gives the licensing terms for the files
+ listed in the <varname>Files</varname> field for this paragraph. In
+ a stand-alone License paragraph, it gives the licensing terms for
+ those paragraphs which reference it.
</para>
<para>
First line: an abbreviated name for the license, or expression
- giving alternatives (see the <link linkend="license-short-name">Short
- name</link> section for a list of standard abbreviations). If
- there are licenses present in the package without a standard short
- name, an arbitrary short name may be assigned for these licenses.
- These arbitrary names are only guaranteed to be unique within a
- single copyright file.
+ giving alternatives (see the <link
+ linkend="license-short-name">Short name</link> section for a list
+ of standard abbreviations). If there are licenses present in the
+ package without a standard short name, an arbitrary short name may
+ be assigned for these licenses. These arbitrary names are only
+ guaranteed to be unique within a single copyright file.
</para>
<para>
- If there are no remaining lines, then all of the short names
- or short names followed by license exceptions making up the
- first line must be described in <link
+ If there are no remaining lines, then all of the short names or
+ short names followed by license exceptions making up the first line
+ must be described in <link
linkend="stand-alone-license-paragraph">stand-alone License
- paragraphs</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
+ paragraphs</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
Debian Policy's requirement for including a copy of the software's
distribution license (<ulink
url="https://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile";>12.5</ulink>),
--
2.14.1
From 502f7f4505cdb6a9de1194ef94d707f671a995dc Mon Sep 17 00:00:00 2001
From: Ben Finney <bignose@debian.org>
Date: Sun, 3 Sep 2017 14:24:04 +1000
Subject: [PATCH 2/6] Link terms to their definitions.
---
copyright-format-1.0.xml | 17 ++++++++++-------
1 file changed, 10 insertions(+), 7 deletions(-)
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index e40a710a..aed6067a 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -498,13 +498,16 @@ License: MPL-1.1
Formatted text, with synopsis.
</para>
<para>
- In the header paragraph, 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
- Files paragraph, this field gives the licensing terms for the files
- listed in the <varname>Files</varname> field for this paragraph. In
- a stand-alone License paragraph, it gives the licensing terms for
- those paragraphs which reference it.
+ In the <link linkend="header-paragraph">header paragraph</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
+ 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.
</para>
<para>
First line: an abbreviated name for the license, or expression
--
2.14.1
From 86f3be7c4c16dd490160e2a28db6ceb89ea42e50 Mon Sep 17 00:00:00 2001
From: Ben Finney <bignose@debian.org>
Date: Sun, 3 Sep 2017 14:24:13 +1000
Subject: [PATCH 3/6] =?UTF-8?q?Clarify=20=E2=80=9Cmakes=20no=20sense?=
=?UTF-8?q?=E2=80=9D=20by=20instead=20stating=20why=20it=20is=20not=20acce?=
=?UTF-8?q?ptable.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
copyright-format-1.0.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index aed6067a..2033825a 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -265,7 +265,7 @@
<para>
It is valid to use <varname>License</varname> in the header
paragraph without an accompanying <varname>Copyright</varname>
- field, but <varname>Copyright</varname> alone makes no sense.
+ field, but <varname>Copyright</varname> alone is not sufficient.
</para>
<section id="example-header-paragraph">
--
2.14.1
From 6c740ee16836f046a1156242022e88666eb99b5b Mon Sep 17 00:00:00 2001
From: Ben Finney <bignose@debian.org>
Date: Sun, 3 Sep 2017 14:24:20 +1000
Subject: [PATCH 4/6] Correct reference specifically to fields in a paragraph.
---
copyright-format-1.0.xml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index 2033825a..f1900944 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -250,9 +250,9 @@
<para>
The <varname>Copyright</varname> and <varname>License</varname>
fields in the <emphasis>header paragraph</emphasis> may complement
- but do not replace the <emphasis>Files paragraphs</emphasis>. If
- present, they summarise the copyright notices or redistribution
- terms for the package as a whole.
+ but do not replace the fields in the <emphasis>Files
+ paragraphs</emphasis>. If present, they summarise the copyright
+ notices or redistribution terms for the package as a whole.
</para>
<para>
For example, when a work has a grant of license under both a
--
2.14.1
From 8c0e804176f71c731fe9febeb8eb04a77d79d0db Mon Sep 17 00:00:00 2001
From: Ben Finney <bignose@debian.org>
Date: Sun, 3 Sep 2017 14:24:29 +1000
Subject: [PATCH 5/6] Use tighter phrasing of copyright holders and license
grant.
---
copyright-format-1.0.xml | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index f1900944..848e8d67 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -333,12 +333,13 @@ Copyright: 2010 Manuela Manpager
License: GPL-2+
</programlisting>
<para>
- In this example, all files are copyright by the upstream and licensed
- under the GPL, version 2 or later, with three exceptions. All the
- Debian packaging files are copyright by the packager, and further one
- specific file providing a new feature is licensed differently.
- Finally, there are some manual pages added to the package, written by
- a third person.
+ In this example, copyright in all files is held by the upstream,
+ and that copyright holder grants license under the GPL, version 2
+ or later. There are three exceptions. All the Debian packaging
+ files have copyright held by the packager, and further one
+ specific file providing a new feature has a different grant of
+ license. Finally, there are some manual pages added to the
+ package, with copyright held by a third person.
</para>
<para>
Since the license of the manual pages is the same as the other
--
2.14.1
From 1bf68292ff9f8617a79d974a54a9e58372644d3e Mon Sep 17 00:00:00 2001
From: Ben Finney <bignose@debian.org>
Date: Sun, 3 Sep 2017 14:24:36 +1000
Subject: [PATCH 6/6] Clarify a potential contradiction in which files have
what license.
---
copyright-format-1.0.xml | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index 848e8d67..ceeacfdb 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -342,11 +342,11 @@ License: GPL-2+
package, with copyright held by a third person.
</para>
<para>
- Since the license of the manual pages is the same as the other
- files in the package, the last paragraph above could instead be
+ 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
- statements in one <varname>Copyright</varname> field. Whether
- to combine paragraphs with the same license is left to the
+ statements in one <varname>Copyright</varname> field. Whether to
+ combine paragraphs with the same grant of license is left to the
discretion of the author of the
<filename>debian/copyright</filename> file.
</para>
--
2.14.1
Attachment:
signature.asc
Description: PGP signature