Re: DEP-5: Updates from a general editing pass
Jonathan Nieder <jrnieder@gmail.com> writes:
> 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 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".
I now have:
<para>
Even where licenses are DFSG-free and mutually compatible, users may
wish for a way to identify software under certain licenses (if, for
example, they have special reasons to avoid certain licenses).
</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 it for the short
>> + description.i
> Micronit: ambiguous antecedant. Suggested fix: s/it/the first line/.
Done.
>> 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"?
Yes, I wasn't very happy with the wording of this the first time around,
but I couldn't figure out how to make it better.
> 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.
That got me pointed in the right direction. How about this?
<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. 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.
</para>
>> @@ -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/
No, field is correct. The example gives the entire field, not just the
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).
State sounds fine to me. Changed.
>> <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.
That's specific to GNU find, or at least isn't in POSIX find. I added:
<para>
This is the same pattern syntax as
<citerefentry><refentrytitle>fnmatch</refentrytitle>
<manvolnum>3</manvolnum></citerefentry> without the
<constant>FNM_PATHNAME</constant> flag, or the argument to the
<literal>-path</literal> test of the GNU <command>find</command>
command, except that <literal>[]</literal> wildcards are not
recognized.
</para>
> 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.
An advantage of having a format version is that one doesn't have to do
things like this. The syntax can be changed as part of a format upgrade,
and there's no need to reserve the characters in advance since they're
unambiguous given the format version and can just be escaped with
backslash during the update process.
> [...]
>> @@ -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?
I wasn't sure, but that was clearly the implication of that section in the
DEP-5 text, so I left it as-is. (And therefore didn't apply that section
of your patch, since I believe that would be a normative change.)
Here's the patch I applied.
commit b87ba9e56ba48d777628e7850b584a2a092f74b6
Author: Russ Allbery <rra@debian.org>
Date: Sun Feb 26 19:25:36 2012 -0800
Additional wording clarifications to copyright-format 1.0
* Additional wording improvements to copyright-format 1.0 for clarity.
Also mention that the Files pattern syntax is the same as fnmatch(3)
and GNU find -path without [] patterns. Thanks, Jonathan Nieder and
Ben Finney.
diff --git a/copyright-format/copyright-format-1.0.xml b/copyright-format/copyright-format-1.0.xml
index 1da4c7e..277a4e0 100644
--- a/copyright-format/copyright-format-1.0.xml
+++ b/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 (if, for
+ example, they have special reasons to avoid certain licenses).
</para>
</section>
@@ -166,8 +166,8 @@
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
- description. See Debian Policy's section 5.6.13, <ulink
+ <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
formatted text field that has no special first line, and
@@ -241,14 +241,17 @@
</listitem>
</itemizedlist>
<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.
- It is possible to use only <varname>License</varname> in the header
+ 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. 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.
</para>
@@ -446,7 +449,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>
@@ -607,6 +610,15 @@ Copyright 2009, 2010 Angela Watts</programlisting>
Any other character following a backslash is an error.
</para>
<para>
+ This is the same pattern syntax as
+ <citerefentry><refentrytitle>fnmatch</refentrytitle>
+ <manvolnum>3</manvolnum></citerefentry> without the
+ <constant>FNM_PATHNAME</constant> flag, or the argument to the
+ <literal>-path</literal> test of the GNU <command>find</command>
+ command, except that <literal>[]</literal> wildcards are not
+ 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
diff --git a/debian/changelog b/debian/changelog
index 110c87c..d2704ca 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -2,6 +2,10 @@ debian-policy (3.9.3.1) UNRELEASED; urgency=low
* Fix cross-reference to control field syntax in Policy 5.4 (source
package control files). Thanks, Jakub Wilk. (Closes: #661412)
+ * Additional wording improvements to copyright-format 1.0 for clarity.
+ Also mention that the Files pattern syntax is the same as fnmatch(3)
+ and GNU find -path without [] patterns. Thanks, Jonathan Nieder and
+ Ben Finney.
* Install the HTML version of upgrading-checklist in the policy.html
directory as upgrading-checklist.html so that it can be deployed on
www.debian.org in a way that will allow links to Policy sections to
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: