X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=copyright-format%2Fcopyright-format.xml;h=7137e67b3040f998cd76d89803ac2214666fb0f2;hb=6d5f4e0d2c088969b86863cdd0033c917054c207;hp=2420631d1ec765edfb1e823b3cf80379376e8893;hpb=bb91a7facf981330bd079b0ba58523b9f28c57ce;p=debian%2Fdebian-policy.git

diff --git a/copyright-format/copyright-format.xml b/copyright-format/copyright-format.xml
index 2420631..7137e67 100644
--- a/copyright-format/copyright-format.xml
+++ b/copyright-format/copyright-format.xml
@@ -13,8 +13,9 @@
 <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>
       <para>
         Copying and distribution of this file, with or without modification, are
@@ -24,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>
@@ -35,15 +38,18 @@
   <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>
-      This is not a proposal to change the policy in the short term.  In
-      particular, nothing in this proposal supersedes or modifies any of the
+      Use of this specification is optional.
+    </para>
+    <para>
+      Nothing in this proposal supersedes or modifies any of the
       requirements specified in Debian Policy regarding the appropriate detail
       or granularity to use when documenting copyright and license status in
       <filename>debian/copyright</filename>.
@@ -78,9 +84,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 may
+      wish a way to identify software under certain licenses (for example,
+      if they have a problem with the Affero GPL).
     </para>
   </section>
 
@@ -88,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,
@@ -124,51 +130,54 @@
       paragraph</link>.
     </para>
     <para>
-      The value of each field is of one of the four types listed below.  The
-      definition for each field in this document indicates which type of
-      value it takes.
+      There are four types of fields.  The definition for each field in this
+      document indicates which type of value it takes.
     </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.
+        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>
-        Another kind of list value has one value per line. For example,
-        <varname>Copyright</varname> can list many copyright statements, 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>
@@ -186,7 +195,7 @@
     </para>
 
     <section id="header-paragraph">
-      <title>Header paragraph (Once)</title>
+      <title>Header paragraph (once)</title>
       <para>
         The following fields may be present in a header paragraph.
       </para>
@@ -240,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.
@@ -258,12 +268,14 @@ Source: http://www.example.com/software/project</programlisting>
     </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
-        more paragraphs.  In the simplest case, a single paragraph can be used
-        which applies to all files and lists all applicable copyrights and
-        licenses.
+        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.
@@ -277,7 +289,7 @@ Source: http://www.example.com/software/project</programlisting>
         </listitem>
         <listitem>
           <para>
-            <link linkend="license-field">Copyright</link>: required.
+            <link linkend="copyright-field">Copyright</link>: required.
           </para>
         </listitem>
         <listitem>
@@ -317,16 +329,27 @@ 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>
 
     <section id="stand-alone-license-paragraph">
-      <title>Stand-alone License Paragraph (Optional, Repeatable)</title>
+      <title>Stand-alone 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
-        <varname>License</varname> field and stand-alone
-        <varname>License</varname> paragraphs to expand the license short names.
+        Stand-alone <varname>License</varname> paragraphs can be used to
+        provide the full license text for a given license once, instead of
+        repeating it in each <varname>Files</varname> paragraph that refers to
+        it.  The first line of the <varname>License</varname> field must be a
+        single license short name or a short name followed by a license
+        exception.
       </para>
       <para>
         The following fields may be present in a stand-alone License
@@ -389,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>
 
@@ -413,7 +437,7 @@ License: MPL-1.1
     <section id="source-field">
       <title><varname>Source</varname></title>
       <para>
-        Formatted text, no synopsis: an explanation from where the upstream
+        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>
@@ -427,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>
@@ -458,20 +483,19 @@ 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
         single copyright file.
       </para>
       <para>
-        Remaining lines: if left blank here, the file
-        <emphasis>must</emphasis> include a <link
+        If there are no remaining lines, then all of the short names
+        or short names followed by license exceptions making up the
+        first line must be described in <link
         linkend="stand-alone-license-paragraph">stand-alone License
-        paragraph</link> matching each license short
-        name listed on the first line.
-        Otherwise, this field should either
+        paragraphs</link>.  Otherwise, this field should either
         include the full text of the license(s) or include a pointer to the
         license file under <filename>/usr/share/common-licenses</filename>. 
         This field should include all text needed in order to fulfill both
@@ -487,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
@@ -508,15 +532,17 @@ License: MPL-1.1
 Copyright 2009 Angela Watts</programlisting>
         and file B has:
 <programlisting>Copyright 2010 Angela Watts</programlisting>
-        the <varname>Copyright</varname> field for a stanza covering both
-        file A and file B need contain only:
+        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>
@@ -537,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>
@@ -585,11 +614,13 @@ 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 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>
 
@@ -616,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.
@@ -631,13 +663,22 @@ 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, trailing
-        <emphasis>dot-zeroes</emphasis> are considered to be equal to plainer
-        version (e.g., <quote>2.0.0</quote> is considered equal to
+        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>).
       </para>
       <para>
@@ -797,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>
@@ -865,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>
@@ -874,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>
@@ -986,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
@@ -1008,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
@@ -1077,28 +1127,30 @@ also delete it here.</programlisting>
         This is a dual-licensed GPL/Artistic work such as Perl:
 <programlisting>License: GPL-1+ or Artistic</programlisting>
         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
-        <literal>and</literal> has the priority over <literal>or</literal>,
-        unless preceded by a comma. For instance:
+<programlisting>License: GPL-2+ and BSD-3-clause</programlisting>
+        For the most complex cases, a comma is used to disambiguate the
+        priority of <literal>or</literal>s and <literal>and</literal>s.
+        The conjunction <quote><literal>and</literal></quote> has priority over
+        <quote><literal>or</literal></quote> unless preceded by a comma. For
+        instance:
       </para>
       <simpara>
         <literal>A or B and C</literal> means <literal>A or (B and C)</literal>.
       </simpara>
       <simpara>
-        <literal>A or B, and C</literal> means <literal>(A or B), and
+        <literal>A or B, and C</literal> means <literal>(A or B) and
         C</literal>.
       </simpara>
       <para>
         This is for a file that has Perl code and classic BSD code in it:
-<programlisting>License: GPL-2+ or Artistic-2.0, and BSD</programlisting>
+<programlisting>License: GPL-2+ or Artistic-2.0, and BSD-3-clause</programlisting>
         A <literal>GPL-2+</literal> work with the <literal>OpenSSL</literal>
         exception is in effect a dual-licensed work that can be redistributed
         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