DEP5: editorial changes
I would like to propose the attached patch, which makes some editorial
changes to the DEP5 draft. It was bugging me that the document structure
was so deep (four levels of sections in some places), and details of
Files were in two places, and so on. So I re-arranged things a bit more
to my liking, and the attached patch is the result.
There should be no change to meaning, unless I screwed up, in which case
please point it out. Otherwise I'll push this in a few days.
=== modified file 'dep5.mdwn'
--- dep5.mdwn 2010-10-28 11:35:36 +0000
+++ dep5.mdwn 2010-11-13 19:54:04 +0000
@@ -83,6 +83,7 @@
See
<http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax>
for details.
+Extra fields can be added to any paragraph. Their name starts by **`X-`**.
There are four kinds values for fields. Each field specifies which
kind is allowed.
@@ -116,18 +117,21 @@
Each field may occur at most once in a paragraph.
-# Implementation
-## Paragraps
-### Header paragraph (Once)
+# Paragraps
+
+There are three kinds of paragraphs: the first one is called
+the "header paragraph". Every other paragraph is either a "Files"
+paragraph or a stand-alone license paragraph.
+This is similar to source and binary package paragraphs
+in `debian/control` files.
+
+## Header paragraph (Once)
* **`Format`**
* Required
* Syntax: single line
* URI of the format specification, such as:
* http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=REVISION
- * Note that the unwieldy length of the URL should be solved in
- future by hosting the specification at a shorter URL (including the
- specification version).
* **`Upstream-Name`**
* Optional
@@ -167,14 +171,14 @@
from a version known to be DFSG-free, even though the current
upstream version is not.
- * **`Copyright`**
- * Optional.
- * Syntax: line based list
- * In the header paragraph (no `Files` 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 `Copyright` below in
- the `Files paragraph` section.
+ * **`Copyright`**
+ * Optional.
+ * Syntax: line based list
+ * In the header paragraph (no `Files` 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 `Copyright` below in
+ the `Files paragraph` section.
Example:
@@ -183,7 +187,7 @@
Upstream-Contact: John Doe <john.doe@example.com>
Source: http://www.example.com/software/project
-### Files paragraph (Repeatable)
+## Files paragraph (Repeatable)
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
@@ -193,7 +197,7 @@
* Required (not in header paragraph).
* Syntax: white space separated list
* List of patterns indicating files covered by the license
- and copyright specified in this paragraph. See "File patterns" below.
+ and copyright specified in this paragraph. See below for details.
* **`Copyright`**
* Required
@@ -247,59 +251,6 @@
* **`Comment`**
* Same as in the header paragraph.
-
-Example:
-
- Files: *
- Copyright: 2008, John Doe <john.doe@example.com>
- 2007, Jane Smith <jane.smith@example.com>
- License: PSF-2
- [LICENSE TEXT]
-
-### Standalone License Paragraph
-Where a set of files are dual (tri, etc) licensed, or when the same license
-occurs multiple times, you can use a single line **`License`** field and
-standalone **`License`** paragraphs to expand the license short names.
-
-Example 1 (tri-licensed files).
-
- 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]
-
-
-Example 2 (recurrent license).
-
- 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]
-
-### Extra fields.
-
-Extra fields can be added to any paragraph. Their name starts by **`X-`**.
-
-## Fields Detail
-
-### Files
-
Filename patterns in the `Files` field are specified using a
simplified shell glob syntax. Patterns are separated by
white space.
@@ -351,8 +302,46 @@
differently. Finally, there are some manual pages added to the package,
written by a third person.
-### License
-#### Short name
+## Standalone License Paragraph (Optional, Repeatable)
+
+Where a set of files are dual (tri, etc) licensed, or when the same license
+occurs multiple times, you can use a single line **`License`** field and
+standalone **`License`** paragraphs to expand the license short names.
+
+Example 1 (tri-licensed files).
+
+ 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]
+
+
+Example 2 (recurrent license).
+
+ 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]
+
+# License specifications
+
+## Short name
Much of the value of a machine-parseable copyright file lies in being able to
correlate the licenses of multiple pieces of software. To that end, this
@@ -458,7 +447,7 @@
> this exception statement from all source files in the program, then
> also delete it here.
-#### Problematic Licenses
+## Problematic Licenses
The following license names are well known, but ambiguously refer to a number
of different licenses, in ways not easily addressed by the use of version
@@ -472,7 +461,9 @@
`PHP` | The PHP license contains terms which can only reasonably be met when applied to the PHP language itself. Since software other than PHP which uses this license will be rejected from Debian, there's no need for a shared standard keyword.
"""]]
-#### Syntax
+
+## Syntax
+
License names are case-insensitive.
In case of multi-licensing, the license short names are separated by `or`
@@ -543,10 +534,10 @@
-## Implementation
-
-### Examples in pseudo-RFC-822 format
-#### Simple
+# Examples in pseudo-RFC-822 format
+
+## Simple
+
A possible `copyright` file for the program 'X Solitaire' distributed in the
Debian source package `xsol`:
@@ -582,7 +573,8 @@
License:
[LICENSE TEXT]
-#### Complex
+## Complex
+
A possible `copyright` file for the program 'Planet Venus', distributed in the
Debian source package `planet-venus`:
@@ -651,7 +643,7 @@
`/usr/share/common-licenses/GPL-2'.
-## Appendix: Note about the use of this format in Debian
+# Appendix: Note about the use of this format in Debian
The Debian Policy (§12.5) demands that each package is accompanied by a file,
`debian/copyright` in source packages and `/usr/share/doc/package/copyright` in
Reply to: