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
Attachment:
copyright-format_copyright-format.xml
Description: XML document
--- 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>