Re: DEP-5: general file syntax
On la, 2010-08-21 at 20:32 +1200, Lars Wirzenius wrote:
> I'm OK with saying that multiline fields should use the Description
> markup, especially noting Charles's point about only using the long
> description part, when appropriate. This simplifies things quite a lot.
> I'll word a concrete patch to propose.
While wording this, I realized that we have more cases: Files has a list
of values (currently comma-separated, but I propose to make it
white-space separated), and Copyright and maybe other fields have a list
of values one per line. I took the liberty of taking this into account.
The relevant new text in the file syntax section:
There are four kinds values for fields. Each field specifies which
kind is allowed.
* Single-line values.
* White space separated lists.
* Line based lists.
* Free-form 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.
Free-form text is formatted the same as the long description in
a package's `Description` field, possibly also using the first
field in a special way, 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.
I'm attaching the exact diff, which lists the type of value for each
field.
Comments?
=== modified file 'dep5.mdwn'
--- dep5.mdwn 2010-08-17 20:47:26 +0000
+++ dep5.mdwn 2010-08-21 09:04:06 +0000
@@ -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.
+* Free-form 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.
+
+Free-form text is formatted the same as the long description in
+a package's `Description` field, possibly also using the first
+field in a special way, 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
+ * Value: single line
* Syntax: One or more URIs, one per line, indicating the primary
point of distribution of the software.
* **`Disclaimer`**
* Optional
* Single occurrence
- * Syntax: Free-form text. On Debian systems, this field can be
+ * Value: free-form text, no special first line
+ * 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: free-form text, with special first line
* 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: