Bug#148194: debian-policy: Clarification needed regarding multi-line fields
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 or more spaces. These will be displayed
| verbatim. If the display cannot be panned horizontally, the
| displaying program will line wrap them "hard" (i.e., without
| taking account of word breaks). If it can they will be allowed
| to trail off to the right. None, one or two initial spaces may
| be deleted, but the number of spaces deleted from each line will
| be the same (so that you can have indenting work correctly, for
| example).
`-------------------
This one is a simple multi line.
,-------------------
| [...]
|
| The part of the field before the first newline is empty; thereafter
| each line has the name of a binary package and the summary description
| line from that binary package. Each line is indented by one space.
|
| [...]
`-------------------
Here it talks about multi lines.
,-------------------
|Section 5.6.18. "`Changes'"
|
| There should be nothing in this field before the first newline; all
| the subsequent lines must be indented by at least one space; blank
| lines must be represented by a line consisting only of a space and a
| full stop.
`-------------------
This field is composed of multi lines, as they are not to be joined in
a single unit, the same as the previous ones.
,-------------------
|Section 5.6.21. "`Files'"
|
| [...]. The remainder of the field is one line per file, each
| line being indented by one space and containing a number of sub-fields
| separated by spaces.
`-------------------
This one is a multi line field as well.
====================
regards,
guillem
Reply to: