Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Russ Allbery]

package debian-policy
severity 148194 normal
retitle 148194 [AMENDMENT 11/04/2006] Permit multi-line fields in debian/control
thanks

Frank Küster <[EMAIL PROTECTED]> writes:

> Russ Allbery <[EMAIL PROTECTED]> wrote:
>> Here is the proposed patch.  Now looking for seconds.

> IIRC, only one person has so far seconded this.  I've not been involved
> here, but it really sounds sensible.  Therefore I second:

Thanks!  Yes, you're the required second second (er).  I am accordingly
retitling this as an amendment.

I'll post a separate message to the dpkg maintainer list and ask them to
look this over and be sure they have no concerns, since the new
requirements rest primarily with their software.

-- 
Russ Allbery ([EMAIL PROTECTED])   

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Lars Wirzenius]

to, 2006-04-06 kello 16:35 -0700, Russ Allbery kirjoitti:
> Jeroen van Wolffelaar <[EMAIL PROTECTED]> writes:
> > On Tue, Mar 28, 2006 at 07:05:28PM -0800, Russ Allbery wrote:
> 
> >> Seconded.  From a lintian perspective, we're intentionally not checking
> >> for wrapped lines in the debian/control file because all of the tools
> >> cope.
> 
> >> If worried about breakage in scripts that parse the .dsc and .changes
> >> files, I think the best thing to do would be to state that wrapping is
> >> permitted in the debian/control file, but not permitted (except for
> >> defined fields that already allow multiline values) in DEBIAN/control,
> >> .changes, or .dsc files.  I believe lintian currently implements
> >> exactly this check.
> 
> >> I can prepare text if there's general agreement that this is the right
> >> direction to go.  I'd been meaning to propose something very much along
> >> these lines myself.
> 
> > Ditto, looking forward for a patch along these lines to second :).
> 
> Here is the proposed patch.  Now looking for seconds.
> 
> --- policy.sgml.orig  2005-12-24 13:41:09.0 -0800
> +++ policy.sgml   2006-04-06 16:34:13.0 -0700
> @@ -2160,7 +2160,11 @@
> dpkg-genchanges to generate the
> .changes file to accompany the upload, and by
> dpkg-source when it creates the .dsc
> -   source control file as part of a source archive.
> +   source control file as part of a source archive. Many fields are
> +   permitted to span multiple lines in debian/control
> +   but not in any other control file. These tools are responsible
> +   for removing the line breaks from such fields when using fields
> +   from debian/control to generate other control files.
>   
>  
>   
> @@ -2332,6 +2336,20 @@
>  multiple entries should be comma separated. This is an
>  optional field.
>
> +
> +   
> + Any parser that interprets the Uploaders field in
> + debian/control should permit it to span multiple
> + lines
> + In the future, the Uploaders field in
> + debian/control (but not other control files)
> + will be permitted to span multiple lines and interpreting
> + a multiline Uploaders field shall be mandatory.
> + . Line breaks in an Uploaders field that spans
> + multiple lines are not significant and the semantic meaning of
> + the field is the same as if the line breaks had not been
> + present.
> +   
>   
>  
>   
> @@ -3822,6 +3840,15 @@
>   
>  
>   
> +   When these fields are used in the debian/control
> +   file, line breaks are permitted before any whitespace
> +   character. Line breaks are not permitted in these fields when
> +   used in any other control file. For consistency it is
> +   recommended that line breaks only be used before the whitespace
> +   following a comma.
> + 
> +
> + 
> For example, a list of dependencies might appear as:
> 
>  Package: mutt

Seconded.

-- 
Crappy tools are not worth it. Find or make better ones.



-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Russ Allbery]

Ben Finney <[EMAIL PROTECTED]> writes:
> On 06-Apr-2006, Russ Allbery wrote:

>> --- policy.sgml.orig 2005-12-24 13:41:09.0 -0800
>> +++ policy.sgml  2006-04-06 16:34:13.0 -0700
>> @@ -2160,7 +2160,11 @@
>>dpkg-genchanges to generate the
>>.changes file to accompany the upload, and by
>>dpkg-source when it creates the .dsc
>> -  source control file as part of a source archive.
>> +  source control file as part of a source archive. Many fields are
>> +  permitted to span multiple lines in debian/control

> Oops: ^^  ^^

Thanks!  Fixed in my version.

-- 
Russ Allbery ([EMAIL PROTECTED])   


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Ben Finney]

On 06-Apr-2006, Russ Allbery wrote:
> --- policy.sgml.orig  2005-12-24 13:41:09.0 -0800
> +++ policy.sgml   2006-04-06 16:34:13.0 -0700
> @@ -2160,7 +2160,11 @@
> dpkg-genchanges to generate the
> .changes file to accompany the upload, and by
> dpkg-source when it creates the .dsc
> -   source control file as part of a source archive.
> +   source control file as part of a source archive. Many fields are
> +   permitted to span multiple lines in debian/control

Oops: ^^  ^^

-- 
 \"I got fired from my job the other day. They said my |
  `\personality was weird. ... That's okay, I have four more."  -- |
_o__)Bug-Eyed Earl, _Red Meat_ |
Ben Finney <[EMAIL PROTECTED]>


signature.asc
Description: Digital signature

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Russ Allbery]

Jeroen van Wolffelaar <[EMAIL PROTECTED]> writes:
> On Tue, Mar 28, 2006 at 07:05:28PM -0800, Russ Allbery wrote:

>> Seconded.  From a lintian perspective, we're intentionally not checking
>> for wrapped lines in the debian/control file because all of the tools
>> cope.

>> If worried about breakage in scripts that parse the .dsc and .changes
>> files, I think the best thing to do would be to state that wrapping is
>> permitted in the debian/control file, but not permitted (except for
>> defined fields that already allow multiline values) in DEBIAN/control,
>> .changes, or .dsc files.  I believe lintian currently implements
>> exactly this check.

>> I can prepare text if there's general agreement that this is the right
>> direction to go.  I'd been meaning to propose something very much along
>> these lines myself.

> Ditto, looking forward for a patch along these lines to second :).

Here is the proposed patch.  Now looking for seconds.

--- policy.sgml.orig2005-12-24 13:41:09.0 -0800
+++ policy.sgml 2006-04-06 16:34:13.0 -0700
@@ -2160,7 +2160,11 @@
  dpkg-genchanges to generate the
  .changes file to accompany the upload, and by
  dpkg-source when it creates the .dsc
- source control file as part of a source archive.
+ source control file as part of a source archive. Many fields are
+ permitted to span multiple lines in debian/control
+ but not in any other control file. These tools are responsible
+ for removing the line breaks from such fields when using fields
+ from debian/control to generate other control files.

 

@@ -2332,6 +2336,20 @@
 multiple entries should be comma separated. This is an
 optional field.
   
+
+ 
+   Any parser that interprets the Uploaders field in
+   debian/control should permit it to span multiple
+   lines
+   In the future, the Uploaders field in
+   debian/control (but not other control files)
+   will be permitted to span multiple lines and interpreting
+   a multiline Uploaders field shall be mandatory.
+   . Line breaks in an Uploaders field that spans
+   multiple lines are not significant and the semantic meaning of
+   the field is the same as if the line breaks had not been
+   present.
+ 

 

@@ -3822,6 +3840,15 @@

 

+ When these fields are used in the debian/control
+ file, line breaks are permitted before any whitespace
+ character. Line breaks are not permitted in these fields when
+ used in any other control file. For consistency it is
+ recommended that line breaks only be used before the whitespace
+ following a comma.
+   
+
+   
  For example, a list of dependencies might appear as:
  
 Package: mutt


-- 
Russ Allbery ([EMAIL PROTECTED])   


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Russ Allbery]

Wouter Verhelst <[EMAIL PROTECTED]> writes:

> Does the current stable dpkg also support this format already?

I believe, but need to confirm, that it supports it for everything except
Uploaders.  Uploaders was just fixed in the recent dpkg updates.  (So we
may want to hold off on Uploaders until etch is released.)

-- 
Russ Allbery ([EMAIL PROTECTED])   


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Wouter Verhelst]

On Wed, Mar 29, 2006 at 03:39:27AM +0300, Guillem Jover wrote:
[...]
> Proposal
> 
> 
> I'd like «Section 5.2. "Source package control files -- `debian/control'"»
> to specify clearly[0] that the following fields contain logical lines:
> 
>   Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep,
>   Pre-Depends, Depends, Recommends, Suggests, Conflicts, Replaces, Provides,
>   Enhances, Uploaders
> 
> Those fields will be unwrapped by newer dpkg scripts when generating
> the .deb, .dsc and .changes files, so the few tools that may not support
> logical lines will be able to cope just fine.
> 
> I've started doing this for some time now with almost all of my
> packages, partially breaking policy (I say partially due to dpkg
> unwrapping the lines, and also due to the current ambiguous situation),

Does the current stable dpkg also support this format already?

-- 
Fun will now commence
  -- Seven Of Nine, "Ashes to Ashes", stardate 53679.4


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Jeroen van Wolffelaar]

On Tue, Mar 28, 2006 at 07:05:28PM -0800, Russ Allbery wrote:
> Guillem Jover <[EMAIL PROTECTED]> writes:
> 
> > Proposal
> > 
> 
> > I'd like «Section 5.2. "Source package control files -- `debian/control'"»
> > to specify clearly[0] that the following fields contain logical lines:
> 
> >   Build-Depends, Build-Depends-Indep, Build-Conflicts, 
> > Build-Conflicts-Indep,
> >   Pre-Depends, Depends, Recommends, Suggests, Conflicts, Replaces, Provides,
> >   Enhances, Uploaders
> 
> > Those fields will be unwrapped by newer dpkg scripts when generating
> > the .deb, .dsc and .changes files, so the few tools that may not support
> > logical lines will be able to cope just fine.
> 
> Seconded.  From a lintian perspective, we're intentionally not checking
> for wrapped lines in the debian/control file because all of the tools
> cope.
> 
> If worried about breakage in scripts that parse the .dsc and .changes
> files, I think the best thing to do would be to state that wrapping is
> permitted in the debian/control file, but not permitted (except for
> defined fields that already allow multiline values) in DEBIAN/control,
> .changes, or .dsc files.  I believe lintian currently implements exactly
> this check.
> 
> I can prepare text if there's general agreement that this is the right
> direction to go.  I'd been meaning to propose something very much along
> these lines myself.

Ditto, looking forward for a patch along these lines to second :).

--Jeroen

-- 
Jeroen van Wolffelaar
[EMAIL PROTECTED] (also for Jabber & MSN; ICQ: 33944357)
http://Jeroen.A-Eskwadraat.nl


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Russ Allbery]

Guillem Jover <[EMAIL PROTECTED]> writes:

> Proposal
> 

> I'd like «Section 5.2. "Source package control files -- `debian/control'"»
> to specify clearly[0] that the following fields contain logical lines:

>   Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep,
>   Pre-Depends, Depends, Recommends, Suggests, Conflicts, Replaces, Provides,
>   Enhances, Uploaders

> Those fields will be unwrapped by newer dpkg scripts when generating
> the .deb, .dsc and .changes files, so the few tools that may not support
> logical lines will be able to cope just fine.

Seconded.  From a lintian perspective, we're intentionally not checking
for wrapped lines in the debian/control file because all of the tools
cope.

If worried about breakage in scripts that parse the .dsc and .changes
files, I think the best thing to do would be to state that wrapping is
permitted in the debian/control file, but not permitted (except for
defined fields that already allow multiline values) in DEBIAN/control,
.changes, or .dsc files.  I believe lintian currently implements exactly
this check.

I can prepare text if there's general agreement that this is the right
direction to go.  I'd been meaning to propose something very much along
these lines myself.

-- 
Russ Allbery ([EMAIL PROTECTED])   

Bug#148194: debian-policy: Clarification needed regarding multi-line fields

[Guillem Jover]

Package: debian-policy
Version: 3.6.2

Hi,

Definitions
===

I'll define «physical line» as the stream of bytes ending with an EOL
character (usually '\n', but it could be DOS style as well). «multi line»
as one or more physical lines with the following ones starting with at
least a space. And «logical line» as a multi line field but all lines
representing only one logical unit, thus those can be joined again
afterwards (a logical line is a multi line, but it may not be true the
other way around). Those definitions are just used in this mail to avoid
confusion.

Proposal


I'd like «Section 5.2. "Source package control files -- `debian/control'"»
to specify clearly[0] that the following fields contain logical lines:

  Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep,
  Pre-Depends, Depends, Recommends, Suggests, Conflicts, Replaces, Provides,
  Enhances, Uploaders

Those fields will be unwrapped by newer dpkg scripts when generating
the .deb, .dsc and .changes files, so the few tools that may not support
logical lines will be able to cope just fine.

I've started doing this for some time now with almost all of my
packages, partially breaking policy (I say partially due to dpkg
unwrapping the lines, and also due to the current ambiguous situation),
as that's how we are told to modify policy, by implementing the changes
first (but I've got a package rejected from NEW now ;). Even before dpkg
support only few tools «broke», at least the PTS is the only that I'm
aware of, and only due to a logical line in Uploaders, all build tools
did cope well with logical lines in Build-Dependencies.


[0] I've done a small «anaylisis of Section 5» [1], where I note down
the ambiguities and non-clear paragraphs in the policy when referring
to «lines» (avoiding fields which do not make sense to support
logical lines). It has also been pointed out several times now, by
at least Manoj, that in policy when writting about lines it refers
to the rfc822 meaning, implying logical lines.

[1] Follows the _analysis of Section 5_  (you may consider skipping this
if your time is lacking):


,---
|Section 5.1. "Syntax of control files"
|
| Each paragraph consists of a series of data fields; each field
| consists of the field name, followed by a colon and then the
| data/value associated with that field.  It ends at the end of the
| line. [...]
`---

It's not clear if those could be logical lines.

,---
| Some fields' values may span several lines; in this case each
| continuation line must start with a space or a tab.  Any trailing
| spaces or tabs at the end of individual lines of a field value are
| ignored.
`---

This is clearly at least a multi line, not clear if it could be a
logical line as well.

,---
| Except where otherwise stated, only a single line of data is allowed
| [...]
`---

Not clear which kind of line.

,---
|Section 5.6.2. "`Maintainer'"
|
| [...]. The name should come first, then the email address inside angle
| brackets `<>' (in RFC822 format).
`

This could be interpreted as if this field would be in rfc822 format
thus supporting logical lines, but it's not clear if it is only
referring to the email address format.

,---
|Section 5.6.4. "`Changed-By'"
|
| [...]. All the rules for the Maintainer field apply here, too.
`---

Same here.

,---
|Section 5.6.10. "Package interrelationship fields: `Depends', `Pre-Depends',
|  `Recommends', `Suggests', `Conflicts', `Provides', `Replaces',
|  `Enhances'"
|
| [...]
| Their syntax and semantics are described in Chapter 7, `Declaring
| relationships between packages'.
`---

Reference to Chapter 7, where we can find:

,---
|Section 7.1. "Syntax of relationship fields"
|
| [...]
|
| For example:
|  Source: glibc
|  Build-Depends-Indep: texinfo
|  Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
|hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
`---

There's no explicit mention of any kind of line in this section, but the
example include an explicit logical line field, and it's also this way in
the source document (this may be argued that was wrapped for editorial
reasons, but it's a clear example in policy).

,---
|Section 5.6.13. "`Description'"
|
| [...]
|
| The lines in the extended description can have these formats:
|
|* Those starting with a single space are part of a paragraph.
|  Successive lines of this form will be word-wrapped when
|  displayed.  The leading space will usually be stripped off.
`---

This one is clearly a logical line.

,---
|* Those starting with two