Re: DEP-5: Updates from a general editing pass
Hi Russ,
Thanks very much for an overall pleasant policy release. Only
nitpicks below.
Russ Allbery wrote:
> +++ b/copyright-format/copyright-format.xml
[...]
> @@ -81,9 +84,9 @@
> no way to know how much of Debian should be stripped from such a system.
> </para>
> <para>
> - Even where licenses are DFSG-free and mutually compatible, users might want
> - a way to avoid software with certain licenses, for example if they have a
> - problem with the Affero GPL.
> + Even where licenses are DFSG-free and mutually compatible, users may
> + wish a way to identify software under certain licenses (for example,
> + if they have a problem with the Affero GPL).
This was hard for me to parse. s/wish a way/wish for a way/ would
help.
By the way, now that there's been a release and we're not in a rush
any more: could you explain this example? I understand that some
people might dislike the Affero GPL for practical or theoretical
reasons, but why does this make a good example of situations in which
users would want to search out software under a particular license?
My confusion might be coming from the phrase "have a problem with",
which in everyday language is mostly synonymous with "have a grudge
against". I would be more convinced by "for example, if they are
running a network-facing service and wish to avoid the Affero GPL", or
more simply, "for example, if they wish to avoid the Affero GPL".
[...]
> @@ -134,43 +137,47 @@
[...]
> + 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 it for the short
> + description.i
Micronit: ambiguous antecedant. Suggested fix: s/it/the first line/.
[...]
> @@ -242,9 +249,10 @@
[...]
> They
> + can be used to summarise the copyright notices or redistribution terms
> + for the whole package, such as when a work combines a
> + permissive and a copyleft license and the combination requires
> + some clarification,
It is not clear what "such as" is meant to be attached to --- "terms
such as"?
Suggested fix: split into two sentences, perhaps like so:
They can be used to summarize ... the whole package. For example,
when a work combines components under permissive and copyleft
licenses, these fields can be a good place to clarify license terms
for the combination.
> or to document a
> <emphasis>compilation copyright</emphasis> and license.
They can also be used to document a /compilation copyright/ and
license.
[...]
> @@ -262,11 +270,12 @@ Source: http://www.example.com/software/project</programlisting>
[...]
> + In the simplest case, a single paragraph
> + with <literal>Files: *</literal> can be used to state the license
> + and copyright for the whole package.
Nicely explained.
[...]
> @@ -394,8 +412,9 @@ License: MPL-1.1
> <section id="format-field">
> <title><varname>Format</varname></title>
> <para>
> - Single-line: URI of the format specification, such as:
> - <literal>http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/</literal>.
> + Single-line: URI of the format specification. The field that
> + should be used for the current version of this document is:
s/field/value/
[...]
> @@ -432,8 +451,9 @@ License: MPL-1.1
> <section id="disclaimer-field">
> <title><varname>Disclaimer</varname></title>
> <para>
> - Formatted text, no synopsis: this field can be used in the case of
> - non-free and contrib packages (see <ulink
> + Formatted text, no synopsis: this field is used for non-free or
> + contrib packages to say that they are not part of Debian and to
> + explain why (see Debian Policy section <ulink
"say" leaves me wondering why we need this information that might be
redundant next to the License fields in debian/copyright and Section
field in debian/control.
Possible fixes: s/say/state/ (to convey that this is ritual) or
s/say/emphasize/ (to convey the purpose of the redundancy).
... This field is used in non-free or
contrib packages to state that they are not part of Debian and to
explain why (see Debian Policy section 12.5).
[...]
> @@ -541,8 +563,11 @@ Copyright 2009, 2010 Angela Watts</programlisting>
> <para>
> Only the wildcards <literal>*</literal> and <literal>?</literal>
> apply; the former matches any number of characters (including
> - none), the latter a single character. Both match a slash
> - (<literal>/</literal>) and a leading dot.
> + none), the latter a single character. Both match slashs
> + (<literal>/</literal>) and leading dots, unlike shell globs.
> + The pattern <literal>*.in</literal> therefore matches any
> + file whose name ends in <literal>.in</literal> anywhere in
> + the source tree, not just at the top level.
It might be worth mentioning somewhere that this is the same syntax
accepted by find's -path primary, except that bracket expressions are
not supported.
Perhaps in copyright-format 1.1, unescaped brackets and single and
double quotation marks should be forbidden, to prepare for
copyright-format 2.0 without commiting to any particular syntax
immediately.
[...]
> @@ -635,11 +663,20 @@ Copyright 2009, 2010 Angela Watts</programlisting>
[...]
> + For licenses that have multiple versions in use, the short name is
> + formed from the general short name of the license family, followed
> + by a dash and the version number. If the version number is
> + omitted, the lowest version number is implied. When the license
> + grant permits using the terms of any later version of that
> + license, add a plus sign to the end of the short name.
Is allowing "GPL+" as a synonym for "GPL-1+" intentional?
[...]
> @@ -1103,7 +1149,8 @@ also delete it here.</programlisting>
> either under the <literal>GPL-2+</literal>, or under the
> <literal>GPL-2+</literal> with the <literal>OpenSSL</literal> exception.
> It is thus expressed as <literal>GPL-2+ with OpenSSL
> - exception</literal>:
> + exception</literal>. A possible <varname>License</varname> field
> + for such a license is:
Looks good. Here's an example patch implementing most of the
suggestions above (though not the -path stuff).
---
copyright-format/copyright-format-1.0.xml | 27 ++++++++++++++-------------
1 file changed, 14 insertions(+), 13 deletions(-)
diff --git i/copyright-format/copyright-format-1.0.xml w/copyright-format/copyright-format-1.0.xml
index 1da4c7ed..67ceb702 100644
--- i/copyright-format/copyright-format-1.0.xml
+++ w/copyright-format/copyright-format-1.0.xml
@@ -80,8 +80,8 @@
</para>
<para>
Even where licenses are DFSG-free and mutually compatible, users may
- wish a way to identify software under certain licenses (for example,
- if they have a problem with the Affero GPL).
+ wish for a way to identify software under certain licenses (for example,
+ if they wish to avoid the Affero GPL).
</para>
</section>
@@ -166,7 +166,7 @@
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 it for the short
+ <varname>Description</varname> field uses the first line for the short
description. See Debian Policy's section 5.6.13, <ulink
url="http://www.debian.org/doc/debian-policy/ch-controlfields#s-f-Description";><quote>Description</quote></ulink>,
for details. For example, <varname>Disclaimer</varname> is a
@@ -243,11 +243,12 @@
<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>. They can be used
- to summarise the copyright notices or redistribution terms for the
- whole package, such as when a work combines a permissive and a
- copyleft license and the combination requires some clarification, or
- to document a <emphasis>compilation copyright</emphasis> and license.
+ replace the <emphasis>Files paragraphs</emphasis>. They summarise the
+ copyright notices or redistribution terms for the whole package.
+ For example, when a work combines a permissive and a copyleft license,
+ these fields can be used to clarify license terms for the combination.
+ They 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.
</para>
@@ -446,7 +447,7 @@ License: MPL-1.1
<title><varname>Disclaimer</varname></title>
<para>
Formatted text, no synopsis: this field is used for non-free or
- contrib packages to say that they are not part of Debian and to
+ contrib packages to state that they are not part of Debian and to
explain why (see Debian Policy section <ulink
url="http://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile";>12.5</ulink>).
</para>
@@ -659,10 +660,10 @@ Copyright 2009, 2010 Angela Watts</programlisting>
<para>
For licenses that have multiple versions in use, the short name is
formed from the general short name of the license family, followed
- by a dash and the version number. If the version number is
- omitted, the lowest version number is implied. When the license
- grant permits using the terms of any later version of that
- license, add a plus sign to the end of the short name. For
+ by a dash and the version number. When the license grant permits
+ using the terms of any later version of that license, add a plus
+ sign to the end of the short name. If the version number and plus
+ sign are omitted, the lowest version number is implied. For
example, the short name <literal>GPL</literal> refers to the GPL
version 1 and is equivalent to <literal>GPL-1</literal>, although
the latter is clearer and therefore preferred. If the package may
Reply to: