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 <vor...@debian.org>, Lars Wirzenius <l...@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.hol...@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