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

diff --git a/copyright-format/copyright-format.xml b/copyright-format/copyright-format.xml
index 8ae9023..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,14 +25,12 @@
     </legalnotice>
     <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. The DEP drivers were Steve Langasek
-        <email>vorlon@debian.org</email> and Lars Wirzenius
-        <email>liw@liw.fi</email>.
+        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>
@@ -40,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>.
@@ -83,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>
 
@@ -93,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,
@@ -123,49 +124,60 @@
       avoid conflicting specifications for widely used extra fields.
     </para>
     <para>
-      There are four kinds values for fields.  Each field specifies which kind
-      is allowed.
+      The file consists of two or more paragraphs.  At minimum, the file
+      must include one <link linkend="header-paragraph">header
+      paragraph</link> and one <link linkend="files-paragraph">Files
+      paragraph</link>.
+    </para>
+    <para>
+      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>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
-        <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>
+      <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>
@@ -173,272 +185,124 @@
   <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
+      There are three kinds of paragraphs.  The first paragraph in the file
+      is called the <link linkend="header-paragraph">header paragraph</link>.
+      Every other paragraph is either a <link
+      linkend="files-paragraph">Files paragraph</link> or a <link
+      linkend="stand-alone-license-paragraph">stand-alone License
+      paragraph</link>.  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>
-      <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>
-
-      <section id="upstream-name-header-field">
-        <title><varname>Upstream-Name</varname></title>
-        <para>
-          Optional single line: the name upstream uses for the software
-        </para>
-      </section>
-
-      <section id="upstream-contact-header-field">
-        <title><varname>Upstream-Contact</varname></title>
-        <para>
-          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>
-      </section>
-
-      <section id="source-header-field">
-        <title><varname>Source</varname></title>
-        <para>
-          Optional formatted text, no synopsis: an explanation from 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>
-          requires this information unless there are no upstream sources, which
-          is mainly the case for native Debian packages. If the upstream source
-          has been modified to remove non-free parts, that should be explained
-          in this field.
-        </para>
-      </section>
-
-      <section id="disclaimer-header-field">
-        <title><varname>Disclaimer</varname></title>
-        <para>
-          Optional formatted text, no synopsis: this field can be used in the
-          case of non-free and contrib packages (see <ulink
-          url="http://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile">12.5</ulink>)
-        </para>
-      </section>
-
-      <section id="comment-header-field">
-        <title><varname>Comment</varname></title>
-        <para>
-          Optional formatted text, no synopsis: this field can provide
-          additional information.  For example, it might quote an e-mail from
-          upstream justifying why the license is acceptable to the main archive,
-          or an explanation of how this version of the package has been forked
-          from a version known to be DFSG-free, even though the current upstream
-          version is not.
-        </para>
-      </section>
-
-      <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>
-
-      <section id="copyright-header-field">
-        <title><varname>Copyright</varname></title>
-        <para>
-          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
-          copyright information.  See also <varname>Copyright</varname> below
-          in the <link linkend="files-paragraph">Files paragraph</link>
-          section.
-        </para>
-        <para>
-          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 <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.
-        </para>
-      </section>
+      <title>Header paragraph (once)</title>
+      <para>
+        The following fields may be present in a header paragraph.
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <link linkend="format-field">Format</link>: required.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="upstream-name-field">Upstream-Name</link>:
+            optional.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link
+            linkend="upstream-contact-field">Upstream-Contact</link>:
+            optional.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="source-field">Source</link>: optional.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="disclaimer-field">Disclaimer</link>:
+            optional.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="comment-field">Comment</link>: optional.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="license-field">License</link>: optional.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="copyright-field">Copyright</link>: optional.
+          </para>
+        </listitem>
+      </itemizedlist>
+      <para>
+        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 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.
+      </para>
 
       <section id="example-header-paragraph">
         <title>Example header paragraph</title>
-<programlisting>Format: &lt;VERSIONED_FORMAT_URL&gt;
+<programlisting>Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: SOFTware
 Upstream-Contact: John Doe &lt;john.doe@example.com&gt;
 Source: http://www.example.com/software/project</programlisting>
       </section>
     </section>
 
-    <section id="files-paragraph">
-      <title>Files paragraph (Repeatable)</title>
+     <section id="files-paragraph">
+      <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.
-      </para>
-
-      <section id="files-files-field">
-        <title><varname>Files</varname></title>
-        <para>
-          Required white space separated list: list of patterns indicating files
-          covered by the license and copyright specified in this paragraph.
-        </para>
-        <para>
-          Filename patterns in the <varname>Files</varname> field are specified
-          using a simplified shell glob syntax.  Patterns are separated by white
-          space.
-        <itemizedlist>
-          <listitem>
-            <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.
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              Patterns match pathnames that start at the root of the source
-              tree.  Thus, <quote><filename>Makefile.in</filename></quote>
-              matches only the file at the root of the tree, but
-              <quote><filename>*/Makefile.in</filename></quote> matches at any
-              depth.
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              The backslash (<literal>\</literal>) is used to remove the magic
-              from the next character; see table below.
-            </para>
-          </listitem>
-        </itemizedlist>
-        <informaltable>
-          <tgroup cols="2">
-            <thead>
-              <row>
-                <entry>Escape sequence</entry>
-                <entry>Matches</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry><literal>\*</literal></entry>
-                <entry>star (asterisk)</entry>
-              </row>
-              <row>
-                <entry><literal>\?</literal></entry>
-                <entry>question mark</entry>
-              </row>
-              <row>
-                <entry><literal>\\</literal></entry>
-                <entry>backslash</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-        Any other character following a backslash is an error.
+        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>
-        Multiple <varname>Files</varname> paragraphs are allowed.  The last
-        paragraph that matches a particular file applies to it.
+        The following fields may be present in a Files paragraph.
       </para>
-      <para>
-        Exclusions are done by having multiple <varname>Files</varname>
-        paragraphs.
-      </para>
-      </section>
 
-      <section id="copyright-files-field">
-        <title><varname>Copyright</varname></title>
-        <para>
-          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.
-        </para>
-        <para>
-          The <varname>Copyright</varname> field collects all relevant copyright
-          notices for the files of this paragraph.  Not all copyright notices
-          may apply to every individual file, and years of publication for one
-          copyright holder may be gathered together.  For example, if file A
-          has:
-<programlisting>Copyright 2008 John Smith
-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:
-<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 does not sacrifice information.  Examples in this specification
-          use both forms.
-        </para>
-      </section>
-
-      <section id="license-files-field">
-        <title><varname>License</varname></title>
-        <para>
-          Required formatted text, with synopsis: licensing terms for the files
-          listed in <varname>Files</varname> field for this paragraph.
-        </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 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 stand-alone
-          <varname>License</varname> paragraph matching each license short
-          name listed on the first line (see the <link
-          linkend="stand-alone-license-paragraph">Standalone License
-          Paragraph</link> section).  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
-          Debian Policy's requirement for including a copy of the software's
-          distribution license (<ulink
-          url="http://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile">12.5</ulink>),
-          and any license requirements to include warranty disclaimers or other
-          notices with the binary package.
-        </para>
-      </section>
-
-      <section id="comment-files-field">
-        <title><varname>Comment</varname></title>
-        <para>
-          Same as the <link linkend="comment-header-field">
-          <varname>Comment</varname></link> field in the header paragraph.
-        </para>
-      </section>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <link linkend="files-field">Files</link>: required.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="copyright-field">Copyright</link>: required.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="license-field">License</link>: required.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="comment-field">Comment</link>: optional.
+          </para>
+        </listitem>
+      </itemizedlist>
 
       <section id="example-files-paragraph">
         <title>Example files paragraphs</title>
@@ -465,17 +329,45 @@ 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>Standalone 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 standalone
-        <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
+        paragraph.
+      </para>
+
+      <itemizedlist>
+        <listitem>
+          <para>
+            <link linkend="license-field">License</link>: required.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <link linkend="comment-field">Comment</link>: optional.
+          </para>
+        </listitem>
+      </itemizedlist>
       <example>
         <title>tri-licensed files</title>
 <programlisting>Files: src/js/editline/*
@@ -490,7 +382,7 @@ License: GPL-2
  [LICENSE TEXT]
 
 License: LGPL-2.1
- LICENSE TEXT]</programlisting>
+ [LICENSE TEXT]</programlisting>
       </example>
 
       <example>
@@ -510,6 +402,229 @@ License: MPL-1.1
     </section>
   </section>
 
+  <section id="fields">
+    <title>Fields</title>
+    <para>
+      The following fields are defined for use in
+      <filename>debian/copyright</filename>.
+    </para>
+
+    <section id="format-field">
+      <title><varname>Format</varname></title>
+      <para>
+        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>
+
+    <section id="upstream-name-field">
+      <title><varname>Upstream-Name</varname></title>
+      <para>
+        Single-line: the name upstream uses for the software
+      </para>
+    </section>
+
+    <section id="upstream-contact-field">
+      <title><varname>Upstream-Contact</varname></title>
+      <para>
+        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>
+    </section>
+
+    <section id="source-field">
+      <title><varname>Source</varname></title>
+      <para>
+        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>
+        requires this information unless there are no upstream sources,
+        which is mainly the case for native Debian packages.  If the
+        upstream source has been modified to remove non-free parts, that
+        should be explained in this field.
+      </para>
+    </section>
+
+    <section id="disclaimer-field">
+      <title><varname>Disclaimer</varname></title>
+      <para>
+        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>
+
+    <section id="comment-field">
+      <title><varname>Comment</varname></title>
+      <para>
+        Formatted text, no synopsis: this field can provide additional
+        information.  For example, it might quote an e-mail from upstream
+        justifying why the license is acceptable to the main archive, or an
+        explanation of how this version of the package has been forked from
+        a version known to be DFSG-free, even though the current upstream
+        version is not.
+      </para>
+    </section>
+
+    <section id="license-field">
+      <title><varname>License</varname></title>
+      <para>
+        Formatted text, with synopsis.  In the header paragraph, 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.  In a Files paragraph, this field gives the
+        licensing terms for the files listed in the <varname>Files</varname>
+        field for this paragraph.  In a stand-alone License paragraph, it
+        gives the licensing terms for those paragraphs which reference it.
+      </para>
+      <para>
+        First line: an abbreviated name for the license, or expression
+        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>
+        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
+        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
+        Debian Policy's requirement for including a copy of the software's
+        distribution license (<ulink
+        url="http://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile">12.5</ulink>),
+        and any license requirements to include warranty disclaimers or
+        other notices with the binary package.
+      </para>
+    </section>
+
+    <section id="copyright-field">
+      <title><varname>Copyright</varname></title>
+      <para>
+        Formatted text, no synopsis: one or more free-form copyright
+        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
+        simplified from a combination of all the per-file copyright
+        information.  In the Files paragraphs, it gives the copyright
+        information that applies to the files matched by the
+        <varname>Files</varname> pattern.  If a work has no copyright holder
+        (i.e., it is in the public domain), that information should be
+        recorded here.
+      </para>
+      <para>
+        The <varname>Copyright</varname> field collects all relevant
+        copyright notices for the files of this paragraph.  Not all
+        copyright notices may apply to every individual file, and years of
+        publication for one copyright holder may be gathered together.  For
+        example, if file A has:
+<programlisting>Copyright 2008 John Smith
+Copyright 2009 Angela Watts</programlisting>
+        and file B has:
+<programlisting>Copyright 2010 Angela Watts</programlisting>
+        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 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>
+    </section>
+
+    <section id="files-field">
+      <title><varname>Files</varname></title>
+      <para>
+        Whitespace-separated list: list of patterns indicating files covered
+        by the license and copyright specified in this paragraph.
+      </para>
+      <para>
+        Filename patterns in the <varname>Files</varname> field are
+        specified using a simplified shell glob syntax.  Patterns are
+        separated by whitespace.
+        <itemizedlist>
+          <listitem>
+            <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 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>
+            <para>
+              Patterns match pathnames that start at the root of the source
+              tree.  Thus, <quote><filename>Makefile.in</filename></quote>
+              matches only the file at the root of the tree, but
+              <quote><filename>*/Makefile.in</filename></quote> matches at
+              any depth.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              The backslash (<literal>\</literal>) is used to remove the
+              magic from the next character; see table below.
+            </para>
+          </listitem>
+        </itemizedlist>
+        <informaltable>
+          <tgroup cols="2">
+            <thead>
+              <row>
+                <entry>Escape sequence</entry>
+                <entry>Matches</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry><literal>\*</literal></entry>
+                <entry>star (asterisk)</entry>
+              </row>
+              <row>
+                <entry><literal>\?</literal></entry>
+                <entry>question mark</entry>
+              </row>
+              <row>
+                <entry><literal>\\</literal></entry>
+                <entry>backslash</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+        Any other character following a backslash is an error.
+      </para>
+      <para>
+        Multiple <varname>Files</varname> paragraphs are allowed.  The last
+        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>
+        paragraphs to override the previous match.
+      </para>
+    </section>
+
+  </section>
   <section id="license-specification">
     <title>License specification</title>
 
@@ -532,7 +647,8 @@ License: MPL-1.1
       <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.
@@ -543,17 +659,26 @@ License: MPL-1.1
         <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 stand-alone License paragraph or in the relevant
         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>
@@ -582,8 +707,8 @@ License: MPL-1.1
               </entry>
               <entry>
                 Apache license
-                <ulink url="http://spdx.org/licenses/ASL-1.0">1.0</ulink>,
-                <ulink url="http://spdx.org/licenses/ASL-2.0">2.0</ulink>.
+                <ulink url="http://spdx.org/licenses/Apache-1.0">1.0</ulink>,
+                <ulink url="http://spdx.org/licenses/Apache-2.0">2.0</ulink>.
               </entry>
             </row>
             <row>
@@ -712,9 +837,10 @@ License: MPL-1.1
                 CC0
               </entry>
               <entry>
-                Creative Commons <ulink
-                url="http://creativecommons.org/license/zero/">Universal
-                waiver</ulink>.
+                Creative Commons Zero
+                <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>
@@ -722,8 +848,8 @@ License: MPL-1.1
                 CDDL
               </entry>
               <entry>
-                <ulink url="http://spdx.org/licenses/CDDL">Common Development
-                and Distribution License</ulink>.
+                Common Development and Distribution License
+                <ulink url="http://spdx.org/licenses/CDDL-1.0">1.0</ulink>.
               </entry>
             </row>
             <row>
@@ -774,7 +900,6 @@ License: MPL-1.1
                 <ulink url="http://spdx.org/licenses/LGPL-2.1">2.1</ulink>,
                 <ulink url="http://spdx.org/licenses/LGPL-3.0">3.0</ulink>, or
                 GNU Library General Public License
-                <ulink url="http://spdx.org/licenses/LGPL-1.0">1.0</ulink>,
                 <ulink url="http://spdx.org/licenses/LGPL-2.0">2.0</ulink>.
               </entry>
             </row>
@@ -783,8 +908,12 @@ License: MPL-1.1
                 GFDL
               </entry>
               <entry>
-                <ulink url="http://spdx.org/licenses/FDL-1.0">GNU Free
-                Documentation License</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>
@@ -792,7 +921,9 @@ License: MPL-1.1
                 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>
@@ -829,12 +960,13 @@ License: MPL-1.1
             </row>
             <row>
               <entry>
-                Python-CNRI
+                Python
               </entry>
               <entry>
-                <ulink url="http://spdx.org/licenses/Python-CNRI">Python
-                license</ulink>.
+                Python license
+                <ulink url="http://spdx.org/licenses/Python-2.0">2.0</ulink>.
               </entry>
+              <!-- See https://fossbazaar.org/pipermail/spdx-legal/2011-February/000010.html -->
             </row>
             <row>
               <entry>
@@ -871,8 +1003,8 @@ License: MPL-1.1
                 Zope
               </entry>
               <entry>
-                Zope Public License
-                  <ulink url="http://spdx.org/licenses/ZPL-1.0">1.0</ulink>,
+                Zope Public License 1.0,
+                  <ulink url="http://spdx.org/licenses/ZPL-1.1">1.1</ulink>,
                   <ulink url="http://spdx.org/licenses/ZPL-2.0">2.0</ulink>,
                   <ulink url="http://spdx.org/licenses/ZPL-2.1">2.1</ulink>.
               </entry>
@@ -887,10 +1019,24 @@ License: MPL-1.1
         matches.
       </para>
       <para>
-        Exceptions and clarifications are signaled in plain text, by appending
+        An exception or clarification to a license is 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.
+        keywords that must be used when referring to the most frequent
+        exceptions.  When exceptions other than these are in effect that modify
+        a common license by granting additional permissions, you may use an
+        arbitrary keyword not taken from the below list of keywords.  When a
+        license differs from a common license because of added restrictions
+        rather than because of added permissions, a distinct short name should
+        be used instead of <literal>with
+        <varname><replaceable>keywords</replaceable></varname>
+        exception</literal>.
+      </para>
+      <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 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
@@ -912,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
@@ -981,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
@@ -1062,7 +1210,7 @@ also delete it here.</programlisting>
         A possible <filename>debian/copyright</filename> file for the program
         <quote>X Solitaire</quote> distributed in the Debian source package
         <literal>xsol</literal>:
-<programlisting><![CDATA[Format: <VERSIONED_FORMAT_URL>
+<programlisting><![CDATA[Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: X Solitaire
 Source: ftp://ftp.example.com/pub/games
 
@@ -1092,7 +1240,7 @@ License: GPL-2+
 
 Files: debian/*
 Copyright: Copyright 1998 Jane Smith <jsmith@example.net>
-License:
+License: GPL-2+
  [LICENSE TEXT]]]></programlisting>
       </para>
     </example>
@@ -1103,7 +1251,7 @@ License:
         A possible <filename>debian/copyright</filename> file for the program
         <quote>Planet Venus</quote>, distributed in the Debian source
         package <literal>planet-venus</literal>:
-<programlisting><![CDATA[Format: <VERSIONED_FORMAT_URL>
+<programlisting><![CDATA[Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: Planet Venus
 Upstream-Contact: John Doe <jdoe@example.com>
 Source: http://www.example.com/code/venus
@@ -1118,7 +1266,7 @@ License: PSF-2
 
 Files: debian/*
 Copyright: 2008, Dan Developer <dan@debian.example.com>
-License:
+License: permissive
  Copying and distribution of this package, with or without
  modification, are permitted in any medium without royalty
  provided the copyright notice and this notice are
@@ -1171,27 +1319,4 @@ License: GPL-2+
     </example>
   </section>
 
-  <section id="appendix">
-    <title>
-      Appendix: Note about the use of this format in Debian
-    </title>
-    <para>
-      The Debian Policy (§<ulink
-      url="http://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile">12.5</ulink>)
-      demands that each package is accompanied by a file,
-      <filename>debian/copyright</filename> in source packages and
-      <filename>/usr/share/doc/package/copyright</filename> in binary packages,
-      that contains a verbatim copy of its copyright and distribution license.
-      In addition, it requires that copyrights must be extractable by mechanical
-      means.  This proposal for machine-readable copyright and license summary
-      files has been crafted for Debian's use, but it is our hope that other
-      software distributions, as well as upstream developers will adopt it, so
-      that review efforts can be easily reproduced and shared.
-    </para>
-    <para>
-      The copyright of the Debian packaging and the history of package
-      maintainers is simply indicated in a <literal>Files: debian/*</literal>
-      paragraph.
-    </para>
-  </section>
 </article>