The current DEP5 document is awkward to read with an eye towards implementation. Several field names are common to more than one paragraph type, yet the definitions of these fields are given as part of the definition of one paragraph type or the other; and as a result, the definitions of each paragraph type are very long and easy to get lost in. I propose to refactor the document to add a new top-level "Fields" section, and to split the definitions of the fields out from the information about their usage in each paragraph type. Patch is attached. Does this look ok? Does anyone think there's a better way to do this? Have I introduced any errors in the conversion? -- Steve Langasek Give me a lever long enough and a Free OS Debian Developer to set it on, and I can move the world. Ubuntu Developer http://www.debian.org/ slangasek@ubuntu.com vorlon@debian.org
=== modified file 'dep5/copyright-format.xml'
--- old/dep5/copyright-format.xml 2011-12-12 08:10:20 +0000
+++ new/dep5/copyright-format.xml 2011-12-12 18:32:57 +0000
@@ -181,100 +181,66 @@
<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/packaging-manuals/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. See also <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>
+ <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 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 id="example-header-paragraph">
<title>Example header paragraph</title>
@@ -285,7 +251,7 @@
</section>
</section>
- <section id="files-paragraph">
+ <section id="files-paragraph">
<title>Files paragraph (Repeatable)</title>
<para>
The declaration of copyright and license for files is done in one or
@@ -293,17 +259,273 @@
which applies to all files and lists all applicable copyrights and
licenses.
</para>
-
- <section id="files-files-field">
- <title><varname>Files</varname></title>
+ <para>
+ The following fields may be present in a Files paragraph.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link linkend="files-field">Files</link>: required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="license-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>
+<programlisting>Files: *
+Copyright: 1975-2010 Ulla Upstream
+License: GPL-2+
+
+Files: debian/*
+Copyright: 2010 Daniela Debianizer
+License: GPL-2+
+
+Files: debian/patches/fancy-feature
+Copyright: 2010 Daniela Debianizer
+License: GPL-3+
+
+Files: */*.1
+Copyright: 2010 Manuela Manpager
+License: GPL-2+</programlisting>
<para>
- Required whitespace-separated list: list of patterns indicating files
- covered by the license and copyright specified in this paragraph.
+ In this example, all files are copyright by the upstream and licensed
+ under the GPL, version 2 or later, with three exceptions. All the
+ Debian packaging files are copyright by the packager, and further one
+ specific file providing a new feature is licensed differently.
+ Finally, there are some manual pages added to the package, written by
+ a third person.
</para>
- <para>
- Filename patterns in the <varname>Files</varname> field are specified
- using a simplified shell glob syntax. Patterns are separated by
- whitespace.
+ </section>
+ </section>
+
+ <section id="stand-alone-license-paragraph">
+ <title>Standalone License Paragraph (Optional, Repeatable)</title>
+ <para>
+ Where a set of files are dual (tri, etc) licensed, or when the same
+ license occurs multiple times, you can use a single line
+ <varname>License</varname> field and standalone
+ <varname>License</varname> paragraphs to expand the license short names.
+ </para>
+ <para>
+ The following fields may be present in a standalone 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/*
+Copyright: 1993, John Doe
+ 1993, Joe Average
+License: MPL-1.1 or GPL-2 or LGPL-2.1
+
+License: MPL-1.1
+ [LICENSE TEXT]
+
+License: GPL-2
+ [LICENSE TEXT]
+
+License: LGPL-2.1
+ [LICENSE TEXT]</programlisting>
+ </example>
+
+ <example>
+ <title>recurrent license</title>
+<programlisting>Files: src/js/editline/*
+Copyright: 1993, John Doe
+ 1993, Joe Average
+License: MPL-1.1
+
+Files: src/js/fdlibm/*
+Copyright: 1993, J-Random Corporation
+License: MPL-1.1
+
+License: MPL-1.1
+ [LICENSE TEXT]</programlisting>
+ </example>
+ </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, such as:
+ <literal>http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/</literal>.
+ Required in <link linkend="header-paragraph">header
+ paragraphs</link>.
+ </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 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-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
+ 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 <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="copyright-field">
+ <title><varname>Copyright</varname></title>
+ <para>
+ Line-based list: one or more free-form copyright statement(s), one
+ per line. 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>
+ 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="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>
@@ -318,14 +540,14 @@
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.
+ <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.
+ The backslash (<literal>\</literal>) is used to remove the
+ magic from the next character; see table below.
</para>
</listitem>
</itemizedlist>
@@ -363,151 +585,9 @@
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>
-
- <section id="example-files-paragraph">
- <title>Example files paragraphs</title>
-<programlisting>Files: *
-Copyright: 1975-2010 Ulla Upstream
-License: GPL-2+
-
-Files: debian/*
-Copyright: 2010 Daniela Debianizer
-License: GPL-2+
-
-Files: debian/patches/fancy-feature
-Copyright: 2010 Daniela Debianizer
-License: GPL-3+
-
-Files: */*.1
-Copyright: 2010 Manuela Manpager
-License: GPL-2+</programlisting>
- <para>
- In this example, all files are copyright by the upstream and licensed
- under the GPL, version 2 or later, with three exceptions. All the
- Debian packaging files are copyright by the packager, and further one
- specific file providing a new feature is licensed differently.
- Finally, there are some manual pages added to the package, written by
- a third person.
- </para>
- </section>
- </section>
-
- <section id="stand-alone-license-paragraph">
- <title>Standalone License Paragraph (Optional, Repeatable)</title>
- <para>
- Where a set of files are dual (tri, etc) licensed, or when the same
- license occurs multiple times, you can use a single line
- <varname>License</varname> field and standalone
- <varname>License</varname> paragraphs to expand the license short names.
- </para>
- <example>
- <title>tri-licensed files</title>
-<programlisting>Files: src/js/editline/*
-Copyright: 1993, John Doe
- 1993, Joe Average
-License: MPL-1.1 or GPL-2 or LGPL-2.1
-
-License: MPL-1.1
- [LICENSE TEXT]
-
-License: GPL-2
- [LICENSE TEXT]
-
-License: LGPL-2.1
- [LICENSE TEXT]</programlisting>
- </example>
-
- <example>
- <title>recurrent license</title>
-<programlisting>Files: src/js/editline/*
-Copyright: 1993, John Doe
- 1993, Joe Average
-License: MPL-1.1
-
-Files: src/js/fdlibm/*
-Copyright: 1993, J-Random Corporation
-License: MPL-1.1
-
-License: MPL-1.1
- [LICENSE TEXT]</programlisting>
- </example>
- </section>
+ </section>
+
</section>
-
<section id="license-specification">
<title>License specification</title>
Attachment:
signature.asc
Description: Digital signature