From 6d5f4e0d2c088969b86863cdd0033c917054c207 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Tue, 21 Feb 2012 12:36:00 -0800
Subject: [PATCH] General editing pass for the copyright format specification

Add a pointer to DEP-5 in the synopsis and change the verb tense
to present from imperative.  Rephrase the introduction to talk about
this document as a specification rather than a proposal.

Explicitly mention Files: * as the way to write a single files
paragraph that covers the entire package.

Mention after one of the examples that the two paragraphs for files
with the same license but different copyright holders could be combined
at the discretion of the document author.

Give the complete correct Format field for the current version of the
document in the description of that field.

Add more explanation for how Disclaimer is used.

Say explicitly that more general files paragraphs should be given
first, followed by more specific overrides.

Update the license list to note that "Universal" is removed from the
version of CC0 when forming the short name, to list the new versions
of the GFDL, and to be more explicit about when to use GFDL-NIV.

Rewording and rephrasing in various places to hopefully make the
text flow better, read more smoothly, and be more idiomatic.

Add multiple additional in-line examples, particularly around the
Files patterns and the formation of license short names.
---
 copyright-format/copyright-format.xml | 181 ++++++++++++++++----------
 1 file changed, 114 insertions(+), 67 deletions(-)

diff --git a/copyright-format/copyright-format.xml b/copyright-format/copyright-format.xml
index 36265a4..7137e67 100644
--- a/copyright-format/copyright-format.xml
+++ b/copyright-format/copyright-format.xml
@@ -13,7 +13,7 @@
 <article class="specification" status="draft" lang="en" id="copyright-format">
   <articleinfo>
     <title>
-      Machine-readable <filename>debian/copyright</filename> file.
+      Machine-readable <filename>debian/copyright</filename> file
     </title>
     <subtitle>Version 1.0</subtitle>
     <legalnotice>
@@ -25,10 +25,12 @@
     </legalnotice>
     <abstract>
       <para>
-        Establish a standard, machine-readable format for
-        <filename>debian/copyright</filename> files within packages and to
-        facilitate automated checking and reporting of licenses for packages
-        and sets of packages.
+        Establishes a standard, machine-readable format for
+        <filename>debian/copyright</filename> files within Debian packages
+        to facilitate automated checking and reporting of licenses for
+        packages and sets of packages.  This specification was originally
+        drafted as
+        <ulink url="http://dep.debian.net/deps/dep5/">DEP-5</ulink>.
       </para>
     </abstract>
   </articleinfo>
@@ -36,11 +38,12 @@
   <section id="introduction">
     <title>Introduction</title>
     <para>
-      This is a proposal to make <filename>debian/copyright</filename>
-      machine-interpretable.  This file is one of the most important files in
-      Debian packaging, yet there is currently no standard format defined for it
-      and its contents vary tremendously across packages, making it difficult to
-      automatically extract licensing information.
+      This document describes a standard, machine-interpretable format for
+      the <filename>debian/copyright</filename> file.  This file is one of
+      the most important files in Debian packaging, but, prior to this
+      specification, no standard format was defined for it and its
+      contents varied tremendously across packages.  This made it
+      difficult to automatically extract licensing information.
     </para>
     <para>
       Use of this specification is optional.
@@ -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).
     </para>
   </section>
 
@@ -91,7 +94,7 @@
     <title>Acknowledgements</title>
     <para>
       Many people have worked on this specification over the years.  The
-      following alphabetical list is incomplete, please suggest missing people:
+      following alphabetical list is incomplete; please suggest missing people:
       Russ Allbery,
       Ben Finney,
       Sam Hocevar,
@@ -134,43 +137,47 @@
     <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.
+        The entire value of a single-line field must be 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>
 
     <section id="white-space-lists">
       <title>Whitespace-separated lists</title>
       <para>
-        A whitespace-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
-        whitespace characters (including space, TAB, and newline).  For
-        example, the <varname>Files</varname> field has a list of filename
-        patterns.
+        Field values defined as whitespace-separated lists may be on one
+        line or many.  Values in the list are separated by one or more
+        whitespace characters (space, tab, or newline).  For example, the
+        <varname>Files</varname> field contains a whitespace-separated
+        list of filename patterns.
       </para>
     </section>
 
     <section id="line-based-lists">
       <title>Line-based lists</title>
       <para>
-        This means that the field has one value per line. For example,
-        <varname>Upstream-Contact</varname> can list contact addresses, one per
-        line.
+        Line-based lists have one value per line. For example, the
+        <varname>Upstream-Contact</varname> field contains a line-based
+        list of contact addresses.
       </para>
     </section>
 
     <section id="formatted-text">
-      <title>Text formatted like package long descriptions</title>
+      <title>Formatted text</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
+        Formatted text fields use the same rules as the long description
+        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
         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.
+        for details.  For example, <varname>Disclaimer</varname> is a
+        formatted text field that has no special first line, and
+        <varname>License</varname> is a formatted text field where the
+        first line indicates the short name or names of the licenses.
       </para>
     </section>
   </section>
@@ -242,9 +249,10 @@
         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 contributions and redistribution terms
-        for the whole package, for instance when a work combines a
-        permissive and a copyleft license, or to document a
+        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
         paragraph, but <varname>Copyright</varname> alone makes no sense.
@@ -262,11 +270,12 @@ Source: http://www.example.com/software/project</programlisting>
      <section id="files-paragraph">
       <title>Files paragraph (repeatable)</title>
       <para>
-        The declaration of copyright and license for files may consist of one or
-        more paragraphs.  In the simplest case, a single paragraph can be used
-        which applies to the whole package.  Only the license and copyright
-        information required by the Debian archive is required to be listed
-        here.
+        The declaration of copyright and license for files may consist of
+        one or more paragraphs.  In the simplest case, a single paragraph
+        with <literal>Files: *</literal> can be used to state the license
+        and copyright for the whole package.  Only the license and
+        copyright information required by the Debian archive is required
+        to be listed here.
       </para>
       <para>
         The following fields may be present in a Files paragraph.
@@ -320,6 +329,15 @@ License: GPL-2+</programlisting>
           Finally, there are some manual pages added to the package, written by
           a third person.
         </para>
+        <para>
+          Since the license of the manual pages is the same as the other
+          files in the package, the last paragraph above could instead be
+          combined with the first paragraph, listing both copyright
+          statements in one <varname>Copyright</varname> field.  Whether
+          to combine paragraphs with the same license is left to the
+          discretion of the author of the
+          <filename>debian/copyright</filename> file.
+        </para>
       </section>
     </section>
 
@@ -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:
+<programlisting>Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/</programlisting>
       </para>
     </section>
 
@@ -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
         url="http://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile">12.5</ulink>).
       </para>
     </section>
@@ -463,8 +483,8 @@ License: MPL-1.1
       </para>
       <para>
         First line: an abbreviated name for the license, or expression
-        giving alternatives (see <link linkend="license-short-name">Short
-        names</link> section for a list of standard abbreviations).  If
+        giving alternatives (see the <link linkend="license-short-name">Short
+        name</link> section for a list of standard abbreviations).  If
         there are licenses present in the package without a standard short
         name, an arbitrary short name may be assigned for these licenses. 
         These arbitrary names are only guaranteed to be unique within a
@@ -491,7 +511,7 @@ License: MPL-1.1
       <title><varname>Copyright</varname></title>
       <para>
         Formatted text, no synopsis: one or more free-form copyright
-        statement(s).  Any formatting is permitted; see the examples below
+        statements.  Any formatting is permitted; see the examples below
         for some ideas for how to structure the field to make it easier to
         read.  In the header paragraph, this field gives the copyright
         information for the package as a whole, which may be different or
@@ -512,15 +532,17 @@ License: MPL-1.1
 Copyright 2009 Angela Watts</programlisting>
         and file B has:
 <programlisting>Copyright 2010 Angela Watts</programlisting>
-        then the <varname>Copyright</varname> field for a paragraph covering both
-        file A and file B only needs to contain:
+        a single paragraph may still be used for both files.  The
+        <varname>Copyright</varname> field for that paragraph would
+        contain:
 <programlisting>Copyright 2008 John Smith
 Copyright 2009, 2010 Angela Watts</programlisting>
       </para>
       <para>
         The <varname>Copyright</varname> field may contain the original
         copyright statement copied exactly (including the word
-        <quote>Copyright</quote>), or it can shorten the text, as long as it
+        <quote>Copyright</quote>), or it may shorten the text or merge it
+        with other copyright statements as described above, as long as it
         does not sacrifice information.  Examples in this specification use
         both forms.
       </para>
@@ -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.
             </para>
           </listitem>
           <listitem>
@@ -589,7 +614,9 @@ Copyright 2009, 2010 Angela Watts</programlisting>
       </para>
       <para>
         Multiple <varname>Files</varname> paragraphs are allowed.  The last
-        paragraph that matches a particular file applies to it.
+        paragraph that matches a particular file applies to it.  More
+        general paragraphs should therefore be given first, followed by
+        more specific overrides.
       </para>
       <para>
         Exclusions are only supported by adding <varname>Files</varname>
@@ -620,7 +647,8 @@ Copyright 2009, 2010 Angela Watts</programlisting>
       <para>
         From time to time, licenses may be added to or removed from the list of
         standard short names.  Such changes in the list of short names will
-        always be accompanied by changes to the recommended
+        always be accompanied by changes to the version of this standard
+        and to the recommended
         <varname>Format</varname> value. Implementers who are parsing copyright
         files should take care not to assume anything about the meaning of
         license short names for unknown <varname>Format</varname> versions.
@@ -635,11 +663,20 @@ Copyright 2009, 2010 Angela Watts</programlisting>
         files paragraph.
       </para>
       <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, versions with trailing
+        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
+        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
+        be distributed under the GPL version 1 or any later version, use a
+        short name of <literal>GPL-1+</literal>.
+      </para>
+      <para>
+        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>).
@@ -801,7 +838,9 @@ Copyright 2009, 2010 Angela Watts</programlisting>
               </entry>
               <entry>
                 Creative Commons Zero
-                <ulink url="http://spdx.org/licenses/CC0-1.0">1.0 Universal</ulink>.
+                <ulink url="http://spdx.org/licenses/CC0-1.0">1.0
+                Universal</ulink>.  Omit <quote>Universal</quote> from the
+                license version when forming the short name.
               </entry>
             </row>
             <row>
@@ -869,8 +908,12 @@ Copyright 2009, 2010 Angela Watts</programlisting>
                 GFDL
               </entry>
               <entry>
-                GNU Free Documentation License 1.0, or
-                <ulink url="http://spdx.org/licenses/GFDL-1.1">1.1</ulink>.
+                GNU Free Documentation License 1.0,
+                <ulink url="http://spdx.org/licenses/GFDL-1.1">1.1</ulink>,
+                <ulink url="http://spdx.org/licenses/GFDL-1.2">1.2</ulink>, or
+                <ulink url="http://spdx.org/licenses/GFDL-1.3">1.3</ulink>.
+                Use GFDL-NIV instead if there are no Front-Cover or
+                Back-Cover Texts or Invariant Sections.
               </entry>
             </row>
             <row>
@@ -878,7 +921,9 @@ Copyright 2009, 2010 Angela Watts</programlisting>
                 GFDL-NIV
               </entry>
               <entry>
-                GNU Free Documentation License, with no invariant sections.
+                GNU Free Documentation License, with no Front-Cover or
+                Back-Cover Texts or Invariant Sections.  Use the same
+                version numbers as GFDL.
               </entry>
             </row>
             <row>
@@ -990,7 +1035,8 @@ Copyright 2009, 2010 Angela Watts</programlisting>
       <para>
         Only one exception may be specified for each license within a given
         license specification.  If more than one exception applies to a single
-        license, an arbitrary short name must be used instead.
+        license, an arbitrary short name indicating that combination of
+        multiple exceptions must be used instead.
       </para>
       <para>
         The GPL <literal>Font</literal> exception refers to the text added to the
@@ -1012,7 +1058,7 @@ statement from your version.</programlisting>
           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
@@ -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:
 <programlisting>License: GPL-2+ with OpenSSL exception
  This program is free software; you can redistribute it
  and/or modify it under the terms of the GNU General Public
-- 
2.39.2