Re: DEP-5: general file syntax
Le Sat, Aug 21, 2010 at 09:09:28PM +1200, Lars Wirzenius a écrit :
>
> +There are four kinds values for fields. Each field specifies which
> +kind is allowed.
> +i
> +* Single-line values.
> +* White space separated lists.
> +* Line based lists.
> +* Free-form text formatted like package long descriptions.
Hi Lars,
I have mixed feelings about adding a extra level of complexity and introduce
a syntax for lists. I think that apart from the Files field, the DEP could
use mostly free-form values in the fields.
In particular for the Copyright field, I am of the opinion that it should be
free form and verbatim, preserving the newlines as they are in
debian/copyright. One minor problem is that Policy §5.1 specifies that if a
field value may not be wrapped, then this field is a single line of white space
separated data, and indeed there is no field in Policy's chapter 5 that is
purely free-form while preserving newlines characters. I have opened #593909 to
disambiguate this.
I also feel a contradiction to call ‘free-form’ some text that is formatted
according to some markup rules, even if they are simple. I propose to replace
instances like:
Free-form text formatted like package long descriptions
by:
Formatted text like package long descriptions
Here are additional comments between quotations of your patch.
> +`Copyright` can list many copyright statements, one per line.
For fine-grained descriptions, I would rather recommend to write a SPDX file in
cooperation with Upstream, and use it to generate a DEP-5 template.
> * **`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.
The syntax of the Upstream-Contact field does not reflect the use intended by
the Perl packaging team, which is to match a Debian package with a CPAN
maintainer. The CPAN maintainer's email address not necessarly the preferred
address to reach the upstream authors (for instance, a mailing list).
Since this thread is not about the Upstream-* fields, let's not go too much in
the details, except that in my opinion, ‘line based list’ is not the most
appropriate format for the Upstream-Contact field's value.
Another potential problem for both fields is that a Debian source package can
be composed by multiple unrelated upstream works.
All in all, I would recommend to make these fields free-form. Packaging teams
that would like to use a more specialised syntax can add their own local
policies on top of the DEP.
> @@ -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.
Since the syntax allows multiple URIs, and since the URIs may be long, I think
that allowing newlines in the field will make it more readable. for instance by
making it free-form (not formatted, see below).
> * **`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
If the extended description finally requires double space for verbatim display,
then how abould calling the ‘special first line’ synopsis, to be closer to the
vocabulary used in the specification of the Description field ?
Have a nice day,
--
Charles Plessy
Tsurumi, Kanagawa, Japan
Reply to: