Re: DEP-5: general file syntax
On su, 2010-08-22 at 15:24 -0700, Russ Allbery wrote:
> It's... okay. It's a little strange, but I don't think it would be
> confusing since it is a summary of the license text in a machine-readable
> format, in essence.
ACK, you and Ben have assured me that it is acceptable, and I've changed
the spec draft. Latest diff attached.
=== modified file 'dep5.mdwn'
--- dep5.mdwn 2010-08-17 20:47:26 +0000
+++ dep5.mdwn 2010-08-23 02:47:59 +0000
@@ -3,7 +3,7 @@
Title: Machine-readable debian/copyright
DEP: 5
State: DRAFT
- Date: 2010-08-18
+ Date: 2010-08-23
Drivers: Steve Langasek <vorlon@debian.org>,
Lars Wirzenius <liw@liw.fi>
URL: http://dep.debian.net/deps/dep5
@@ -70,6 +70,36 @@
<http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax>
for details.
+There are four kinds values for fields. Each field specifies which
+kind is allowed.
+
+* Single-line values.
+* White space separated lists.
+* Line based lists.
+* Text formatted like package long descriptions.
+
+A single-line value means that the whole value of a field must fit on
+a single line. For example, the `Format` field has a single line value
+specifying the version of the machine-readable format that is used.
+
+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 `Files` field has a list of filename patterns.
+
+Another kind of list value has one value per line. For example,
+`Copyright` can list many copyright statements, one per line.
+
+Formatted text fields use the same rules as the long description in
+a package's `Description` field, possibly also using the first
+line as a synopsis, like `Description` uses it for the
+short description.
+See section 5.6.13, "Description", at
+<http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description>
+for details.
+For example, `Disclaimer` has no special first line, whereas
+`License` does.
+
# Implementation
## Sections
### Header Section (Once)
@@ -77,6 +107,7 @@
* **`Format`**
* Required
* Single occurrence
+ * Value: single line
* Syntax: 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
@@ -86,12 +117,14 @@
* **`Upstream-Name`**
* Optional
* Single occurrence
+ * Value: single line
* Syntax: Single line (in most cases a single word),
containing the name upstream uses for the software.
* **`Upstream-Contact`**
* Optional
* Single occurrence
+ * Value: line based list
* Syntax: Line(s) containing 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 RFC2822 addresses or URIs.
@@ -99,13 +132,15 @@
* **`Source`**
* Optional
* Single occurrence
- * Syntax: One or more URIs, one per line, indicating the primary
- point of distribution of the software.
+ * Value: line based list
+ * Syntax: One or more URIs, indicating the primary
+ points of distribution of the software.
* **`Disclaimer`**
* Optional
* Single occurrence
- * Syntax: Free-form text. On Debian systems, this field can be
+ * Value: formatted text, no synopsis
+ * Syntax: On Debian systems, this field can be
used in the case of non-free and contrib packages (see [Policy
12.5](
http://www.debian.org/doc/debian-policy/ch-docs.html#s-copyrightfile))
@@ -132,13 +167,15 @@
* Required for all but the first paragraph.
If omitted from the first paragraph,
this is equivalent to a value of '*'.
+ * Value: white space separated list
* Syntax: List of patterns indicating files covered by the license
and copyright specified in this paragraph. See "File patterns" below.
* **`Copyright`**
* Required
- * Syntax: one or more free-form copyright statement(s) that apply to
- the files matched by the above pattern.
+ * Value: line based list
+ * Syntax: one or more free-form copyright statement(s), one per line,
+ that apply to the files matched by the above pattern.
* Example value: 2008, John Q. Holder <john.holder@example.org>
* If a work has no copyright holder (i.e., it is in the public
domain), that information should be recorded here.
@@ -146,6 +183,7 @@
* **`License`**
* Licensing terms for the files listed in **`Files`** field for this section
* Required
+ * Value: formatted text, with synopsis
* Syntax:
* First line: an abbreviated name for the license (see *Short names*
section for a list of standard abbreviations). If empty, it is
Reply to: