[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Can you proofread DEP 5 ?



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: application/xml

--- 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>

Reply to: