Package: debian-policy
Version: 3.9.2
Severity: wishlist
X-Debbugs-CC: debian-l10n-engl...@lists.debian.org
Dear Justin and everybody,
thanks a lot Justin for the proofreading. I read it in details and agree with
all the changes you propose. I therefore propose to the debian-policy team to
apply your patch. To consolidate related changes, let's wait however a little
for additional propositions. For instance, I would like to suggest to replace
“dash” by “hyphen”, so that grepping the source files of the debian-policy
package would conveniently return only lines about the shell called “dash”.
Have a nice day,
-- Charles Plessy, Tsurumi, Kanagawa, Japan
Le Thu, Nov 10, 2011 at 05:28:13PM +0000, Justin B Rye a écrit :
> Charles Plessy wrote:
> > Subject: Re: Can you proofread DEP 5 ?
>
> No space before a question mark! Okay; inline comments, attached
> patch and modified version.
>
> > <?xml version="1.0" encoding="utf-8"?>
> > <?xml-stylesheet type="text/xsl"
> >
> > href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl";?>
> [...]
> > <abstract>
> > <para>
> > This specification was drafted as <ulink
> > url="http://dep.debian.net/deps/dep5/";>DEP-5</ulink>, to establish a
> > standard, machine-readable format for
> > <filename>debian/copyright</filename> files within packages and
> > facilitate automated checking and reporting of licenses for
> > packages and
> > sets of packages.
> > </para>
> > </abstract>
> > </articleinfo>
>
> I suppose "was drafted" is valid, it's just a pity that getting
> drafted is also something that happens to people in wartime. I would
> suggest using "was drawn up".
>
> It would be slightly easier to keep track of the syntax with an extra
> "to": "to establish [...] and ^to^ facilitate [...]".
>
> > <section id="rationale">
> [...]
> > <para>
> > A user might want to have a way to avoid software with certain
> > licenses
> > they have a problem with, even if the licenses are DFSG-free. For
> > example,
> > the Affero GPL.
> > </para>
>
> I think after all the paragraphs about conflict-spotting this one
> would fit in more smoothly with a bit of shuffling:
>
> <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.
> </para>
>
> Then in the syntax section at last we get a definite syntax error:
>
> > <para>
> > There are four kinds values for fields. Each field specifies which
> > kind
> > is allowed.
> > </para>
>
> "Four kinds of values". But I'm not sure I follow this, unless it
> simply means:
>
> <para>
> Each field must have one of the following four types of value.
> </para>
>
> > <section id="single-line">
> > <title>Single-line values</title>
> > <para>
> > A single-line value means that the whole value of a field must fit
> > on a
> > single line. For example, the <varname>Format</varname> field has a
> > single line value specifying the version of the machine-readable
> > format
> > that is used.
> > </para>
> > </section>
>
> A single-line value doesn't mean that; the term "single-line value"
> means that. Or to simplify, "This means..."
>
> And I suppose since I'm here to nitpick I should make this
> consistently hyphenated as "single-line".
>
> > <section id="white-space-lists">
> > <title>White space separated lists</title>
> > <para>
> > A white space separated list means that the field value may be on
> > one
> > line or many, but values in the list are separated by one or more
> > white
> > space characters (including space, TAB, and newline). For example,
> > the
> > <varname>Files</varname> field has a list of filename patterns.
> > </para>
> > </section>
>
> Again, "This means". And you mean "Whitespace-separated" (here and
> elsewhere); "white space" is a graphic design term, not a category of
> character.
>
> > <section id="line-based-lists">
> > <title>Line based lists</title>
> > <para>
> > Another kind of list value has one value per line. For example,
> > <varname>Copyright</varname> can list many copyright statements,
> > one per
> > line.
> > </para>
> > </section>
>
> Again, "line-based" (also where this format is mentioned below).
>
> > <section id="formatted-text">
> > <title>Text formatted like package long descriptions</title>
> > <para>
> > Formatted text fields use the same rules as the long description in
> > a
> > package's <varname>Description</varname> field, possibly also using
> > the
> > first line as a synopsis, like <varname>Description</varname> uses
> > it
> > 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> has no
> > special
> > first line, whereas <varname>License</varname> does.
> > </para>
> > </section>
> > </section>
>
> That use of "like" plus verb phrase (i.e. as in the <para> but not the
> <title>) is sometimes deprecated as colloquial; substitute "just as".
>
> > <section id="paragraphs">
> > <title>Paragraphs</title>
> > <para>
> > There are three kinds of paragraphs: the first one is called the
> > <link linkend="header-paragraph">header paragraph</link>. Every other
> > paragraph is either a <link linkend="files-paragraph">Files</link>
> > paragraph or a <link
> > linkend="stand-alone-license-paragraph">stand-alone
> > license</link> paragraph. This is similar to source and binary
> > package
> > paragraphs in <filename>debian/control</filename> files.
> > </para>
>
> I'd be inclined to say "standalone", and in fact I see that used below.
>
> >
> > <section id="header-paragraph">
> > <title>Header paragraph (Once)</title>
>
> That should be uncapitalised "(once)".
>
> > <section id="format-header-field">
> > <title><varname>Format</varname></title>
> > <para>
> > Required single line: URI of the format specification, such as:
> > <literal>http://www.debian.org/doc/copyright-format/1.0</literal>
> > </para>
> > </section>
>
> Multiple colons isn't as bad as it sounds, but still, drop the second.
>
> [...]
> > <section id="source-header-field">
> > <title><varname>Source</varname></title>
> > <para>
> > Optional formatted text, no synopsis: an explanation from where
> > the
> of
> > upstream source came from. Typically this would be a URL, but it
> > might
>
> [...]
> > <section id="license-header-field">
> > <title><varname>License</varname></title>
> > <para>
> > Optional formatted text, with synopsis: in the header paragraph
> > (no <varname>Files</varname> specification), 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. <varname>License</varname> below in the <link
> > linkend="files-paragraph">Files paragraph</link> section.
> > </para>
> > </section>
>
> I think there's a missing "See also" in the final sentence.
>
> [...]
> > <section id="files-paragraph">
> > <title>Files paragraph (Repeatable)</title>
>
> Again, uncapitalised: "(repeatable)".
>
> > <para>
> > The declaration of copyright and license for files is done in one or
> > more paragraphs. In the simplest case, a single paragraph can be
> > used
> > which applies to all files and lists all applicable copyrights and
> > licenses.
> > </para>
>
> "Is done" is a slightly odd way of phrasing it. How about "may
> consist of"?
>
> [...]
> > <para>
> > Multiple <varname>Files</varname> paragraphs are allowed. The last
> > paragraph that matches a particular file applies to it.
> > </para>
> > <para>
> > Exclusions are done by having multiple <varname>Files</varname>
> > paragraphs.
> > </para>
> > </section>
>
> I take it this means something like:
>
> Exclusions are only supported by adding <varname>Files</varname>
> paragraphs to override the previous match.
>
> [...]
> > <para>
> > Remaining lines: if left blank here, the file
> > <emphasis>must</emphasis> include a stand-alone
> > <varname>License</varname> paragraph matching each license short
> > name listed on the first line (see the <link
>
> s/if left blank here/if these are omitted/, because it isn't the file
> that's left blank and the lines that are omitted aren't here.
>
> [...]
> > <section id="stand-alone-license-paragraph">
> > <title>Standalone License Paragraph (Optional, Repeatable)</title>
>
> An outbreak of surplus capitalisation.
>
> > <para>
> > Where a set of files are dual (tri, etc) licensed, or when the same
> > license occurs multiple times, you can use a single line
> > <varname>License</varname> field and standalone
> > <varname>License</varname> paragraphs to expand the license short
> > names.
> > </para>
>
> "Dual-licensed" ought to be hyphenated, which leads to trouble with
> the intervening parenthesis. Perhaps it should be
>
> Where a set of files are covered by multiple licenses, or one
> license occurs multiple times, you can use a single line
>
> [...]
> > <para>
> > For licenses which have multiple versions in use, the version
> > number is
> > added, using a dash as a separator. If omitted, the lowest version
> > number is implied. When the license grant permits using the terms
> > of any
> > later version of that license, the short name is finished with a
> > plus
> > sign. For <link linkend="spdx">SPDX</link> compatibility, trailing
> > <emphasis>dot-zeroes</emphasis> are considered to be equal to
> > plainer
> > version (e.g., <quote>2.0.0</quote> is considered equal to
> > <quote>2.0</quote> and <quote>2</quote>).
> > </para>
>
> "Plainer version" isn't entirely self-explanatory; I suppose with the
> examples it's fair enough, but I would prefer something like "versions
> with trailing <emphasis>dot-zeroes</emphasis> are considered to be
> equivalent to versions without".
>
> [...]
> > <row>
> > <entry>
> > CC-BY-SA
> > </entry>
> > <entry>
> > Creative Commons Attribution Share Alike license
> > <ulink
> > url="http://spdx.org/licenses/CC-BY-SA-1.0";>1.0</ulink>,
> > <ulink
> > url="http://spdx.org/licenses/CC-BY-SA-2.0";>2.0</ulink>,
> > <ulink
> > url="http://spdx.org/licenses/CC-BY-SA-2.5";>2.5</ulink>,
> > <ulink
> > url="http://spdx.org/licenses/CC-BY-SA-3.0";>3.0</ulink>.
> > </entry>
> > </row>
>
> spdx.org is down just now, but creativecommons.org consistently
> expands this as "Attribution-ShareAlike", ND as "NoDerivs", and NC as
> "NonCommercial". Then again, creativecommons.org seems to spell
> CC-BY-SA etc without the first hyphen, and nobody pays any attention
> to that, so never mind.
>
> [...]
> > <para>
> > Exceptions and clarifications are signaled in plain text, by
> > appending
> > <literal>with <varname><replaceable>keywords</replaceable></varname>
> > exception</literal> to the short name. This document provides a
> > list of
> > keywords that refer to the most frequent exceptions.
> > </para>
>
> If we're standardising to en_GB that's "signalled".
>
> [...]
>
> > For more information, see <ulink
> > url="http://www.gnome.org/~markmc/openssl-and-the-gpl";>The -OpenSSL License
> > and
> > The GPL</ulink> by Mark
>
> Oops, surplus hyphen; plain "OpenSSL".
>
> [...]
> > For the most complex cases, the comma is used to disambiguate the
> > priority of <literal>or</literal>s and <literal>and</literal>s
>
> Should there be a break (maybe just a semicolon) here?
>
> > <literal>and</literal> has the priority over <literal>or</literal>,
> > unless preceded by a comma. For instance:
> [...]
>
> --
> JBR with qualifications in linguistics, experience as a Debian
> sysadmin, and probably no clue about this particular package
--- copyright-format_copyright-format.xml.pristine 2011-11-10
14:56:55.883165353 +0000
+++ copyright-format_copyright-format.xml 2011-11-10 17:23:08.967498468
+0000
@@ -25,10 +25,10 @@
</legalnotice>
<abstract>
<para>
- This specification was drafted as <ulink
+ This specification was drawn up as <ulink
url="http://dep.debian.net/deps/dep5/";>DEP-5</ulink>, to establish a
standard, machine-readable format for
- <filename>debian/copyright</filename> files within packages and
+ <filename>debian/copyright</filename> files within packages and to
facilitate automated checking and reporting of licenses for packages
and
sets of packages.
</para>
@@ -81,9 +81,9 @@
no way to know how much of Debian should be stripped from such a system.
</para>
<para>
- A user might want to have a way to avoid software with certain licenses
- they have a problem with, even if the licenses are DFSG-free. For
example,
- the Affero GPL.
+ 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.
</para>
</section>
@@ -121,32 +121,31 @@
avoid conflicting specifications for widely used extra fields.
</para>
<para>
- There are four kinds values for fields. Each field specifies which kind
- is allowed.
+ Each field must have one of the following four types of value.
</para>
<section id="single-line">
<title>Single-line values</title>
<para>
- A single-line value means that the whole value of a field must fit on a
+ This means that the whole value of a field must fit on a
single line. For example, the <varname>Format</varname> field has a
- single line value specifying the version of the machine-readable format
+ single-line value specifying the version of the machine-readable format
that is used.
</para>
</section>
<section id="white-space-lists">
- <title>White space separated lists</title>
+ <title>Whitespace-separated lists</title>
<para>
- A white space separated list means that the field value may be on one
- line or many, but values in the list are separated by one or more white
- space characters (including space, TAB, and newline). For example, the
+ This means that the field value may be on one
+ line or many, but values in the list are separated by one or more
+ whitespace characters (including space, TAB, and newline). For
example, the
<varname>Files</varname> field has a list of filename patterns.
</para>
</section>
<section id="line-based-lists">
- <title>Line based lists</title>
+ <title>Line-based lists</title>
<para>
Another kind of list value has one value per line. For example,
<varname>Copyright</varname> can list many copyright statements, one
per
@@ -159,7 +158,7 @@
<para>
Formatted text fields use the same rules as the long description in a
package's <varname>Description</varname> field, possibly also using the
- first line as a synopsis, like <varname>Description</varname> uses it
+ first line as a synopsis, just as <varname>Description</varname> uses
it
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> has no special
@@ -174,17 +173,17 @@
There are three kinds of paragraphs: the first one is called the
<link linkend="header-paragraph">header paragraph</link>. Every other
paragraph is either a <link linkend="files-paragraph">Files</link>
- paragraph or a <link linkend="stand-alone-license-paragraph">stand-alone
+ paragraph or a <link linkend="stand-alone-license-paragraph">standalone
license</link> paragraph. This is similar to source and binary package
paragraphs in <filename>debian/control</filename> files.
</para>
<section id="header-paragraph">
- <title>Header paragraph (Once)</title>
+ <title>Header paragraph (once)</title>
<section id="format-header-field">
<title><varname>Format</varname></title>
<para>
- Required single line: URI of the format specification, such as:
+ Required single line: URI of the format specification, such as
<literal>http://www.debian.org/doc/copyright-format/1.0</literal>
</para>
</section>
@@ -199,7 +198,7 @@
<section id="upstream-contact-header-field">
<title><varname>Upstream-Contact</varname></title>
<para>
- Optional line based list: the preferred address(es) to reach the
+ Optional line-based list: the preferred address(es) to reach the
upstream project. May be free-form text, but by convention will
usually be written as a list of RFC5322 addresses or URIs.
</para>
@@ -208,7 +207,7 @@
<section id="source-header-field">
<title><varname>Source</varname></title>
<para>
- Optional formatted text, no synopsis: an explanation from where the
+ Optional formatted text, no synopsis: an explanation of where the
upstream source came from. Typically this would be a URL, but it
might
be a free-form explanation. The Debian Policy section <ulink
url="http://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile";>12.5</ulink>
@@ -247,7 +246,7 @@
(no <varname>Files</varname> specification), 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. <varname>License</varname> below in the <link
+ information. See also <varname>License</varname> below in the <link
linkend="files-paragraph">Files paragraph</link> section.
</para>
</section>
@@ -255,7 +254,7 @@
<section id="copyright-header-field">
<title><varname>Copyright</varname></title>
<para>
- Optional line based list: in the header paragraph (no
+ Optional line-based list: in the header paragraph (no
<varname>Files</varname> specification), 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
@@ -286,9 +285,9 @@
</section>
<section id="files-paragraph">
- <title>Files paragraph (Repeatable)</title>
+ <title>Files paragraph (repeatable)</title>
<para>
- The declaration of copyright and license for files is done in one or
+ The declaration of copyright and license for files may consistof one or
more paragraphs. In the simplest case, a single paragraph can be used
which applies to all files and lists all applicable copyrights and
licenses.
@@ -297,7 +296,7 @@
<section id="files-files-field">
<title><varname>Files</varname></title>
<para>
- Required white space separated list: list of patterns indicating
files
+ Required whitespace-separated list: list of patterns indicating files
covered by the license and copyright specified in this paragraph.
</para>
<para>
@@ -360,15 +359,15 @@
paragraph that matches a particular file applies to it.
</para>
<para>
- Exclusions are done by having multiple <varname>Files</varname>
- paragraphs.
+ Exclusions are only supported by adding <varname>Files</varname>
+ paragraphs to override the previous match.
</para>
</section>
<section id="copyright-files-field">
<title><varname>Copyright</varname></title>
<para>
- Required line based list: one or more free-form copyright
+ Required line-based list: one or more free-form copyright
statement(s), one per line, that apply to the files matched by the
above pattern. If a work has no copyright holder (i.e., it is in
the public domain), that information should be recorded here.
@@ -413,8 +412,8 @@
copyright file.
</para>
<para>
- Remaining lines: if left blank here, the file
- <emphasis>must</emphasis> include a stand-alone
+ Remaining lines: if these are omitted, the file
+ <emphasis>must</emphasis> include a standalone
<varname>License</varname> paragraph matching each license short
name listed on the first line (see the <link
linkend="stand-alone-license-paragraph">Standalone License
@@ -467,10 +466,10 @@
</section>
<section id="stand-alone-license-paragraph">
- <title>Standalone License Paragraph (Optional, Repeatable)</title>
+ <title>Standalone license paragraph (optional, repeatable)</title>
<para>
- Where a set of files are dual (tri, etc) licensed, or when the same
- license occurs multiple times, you can use a single line
+ Where a set of files are covered by multiple licenses, or one
+ license occurs multiple times, you can use a single-line
<varname>License</varname> field and standalone
<varname>License</varname> paragraphs to expand the license short
names.
</para>
@@ -541,7 +540,7 @@
<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
+ field, either in a standalone license paragraph or in the relevant
files paragraph.
</para>
<para>
@@ -549,9 +548,9 @@
added, using a dash as a separator. If omitted, the lowest version
number is implied. When the license grant permits using the terms of
any
later version of that license, the short name is finished with a plus
- sign. For <link linkend="spdx">SPDX</link> compatibility, trailing
- <emphasis>dot-zeroes</emphasis> are considered to be equal to plainer
- version (e.g., <quote>2.0.0</quote> is considered equal to
+ sign. For <link linkend="spdx">SPDX</link> compatibility, versions
with trailing
+ <emphasis>dot-zeroes</emphasis> are considered to be equivalent to
+ versions without (e.g., <quote>2.0.0</quote> is considered equal to
<quote>2.0</quote> and <quote>2</quote>).
</para>
<para>
@@ -885,7 +884,7 @@
matches.
</para>
<para>
- Exceptions and clarifications are signaled in plain text, by appending
+ Exceptions and clarifications are signalled in plain text, by appending
<literal>with <varname><replaceable>keywords</replaceable></varname>
exception</literal> to the short name. This document provides a list
of
keywords that refer to the most frequent exceptions.
@@ -910,7 +909,7 @@
The GPL <literal>OpenSSL</literal> exception gives permission to
link GPL-licensed
code with the OpenSSL library, which contains GPL-incompatible clauses.
For more information, see <ulink
-url="http://www.gnome.org/~markmc/openssl-and-the-gpl";>The -OpenSSL License and
+url="http://www.gnome.org/~markmc/openssl-and-the-gpl";>The OpenSSL License and
The GPL</ulink> by Mark
McLoughlin and the message <ulink
url="http://lists.debian.org/debian-legal/2004/05/msg00595.html";>middleman
@@ -981,7 +980,7 @@
This is for a file that has both GPL and classic BSD code in it:
<programlisting>License: GPL-2+ and BSD</programlisting>
For the most complex cases, the comma is used to disambiguate the
- priority of <literal>or</literal>s and <literal>and</literal>s
+ priority of <literal>or</literal>s and <literal>and</literal>s;
<literal>and</literal> has the priority over <literal>or</literal>,
unless preceded by a comma. For instance:
</para>
