Bug#593909: debian-policy: Clarifications about the syntax of Debian control files.
Charles Plessy <plessy@debian.org> writes:
> Non-wrappable field values
> --------------------------
> §5.1 contains the following paragraph:
> In fields where it is specified that lines may not wrap, only a single
> line of data is allowed and whitespace is not significant in a field
> body. Whitespace must not appear inside names (of packages,
> architectures, files or anything else) or version numbers, or between
> the characters of multi-character version relationships.
What this paragraph means by "wrap" is "may span multiple lines," and it's
also really not correct about whitespace. I think what this paragraph
should say is something like:
In fields where the value may not span multiple lines, the amount of
whitespace in the field body is not significant. Any amount of
whitespace is equivalent to a single space. Whitespace must not
appear inside names (of packages, architectures, files, or anything
else) or version numbers, or between the characters of multi-character
versoin relationships.
> The Architecture and Closes fields seem to follow this convention,
> without referring to it (they do not specify that ‘lines may not
> wrap’). The Distribution also allows a list of values, but not for the
> Debian archive. The Binary field also contains a space-separated list
> of items, but is wrappable.
"Wrap" is a very bad term to use here, since it implies something about
presentation. That's not the intention of the paragraph; rather, it's
talking about whether or not the field body may contain newlines.
> Many other fields are single line, but they do not contain a list of
> space-separated items. For instance, the Maintainer and Urgencey fields.
Indeed. But I don't think we imply that it does.
> Policy chapter 5 contains only two times the word “wrap”, one in the
> above quotation and one in the context of the Description field
> (§5.6.13), in the part that explain how to specify verbatim parts in
> extened descriptions.
The second use is correct, and we should definitely fix the first.
> I am working on DEP-5, which aims at using the Debian control file
> format, I have the feeling that the paragraph that I quoted above makes
> it more difficult to describe how text can be wrapped or not on
> multi-line fields. Unless it has a crucial role that I have overlooked,
> I propose its supppression.
It's saying a bunch of things that aren't said elsewhere, so I don't think
there's any way that we could just drop it.
> Ordering of the paragraphs
> --------------------------
> I always had the impression that the Debian control files had one header
> paragraph, followed by other paragraphs that were not ordered. If it is
> not the case, that is: if parsers are required to remember the order of
> the paragraphs. I think that it would be useful to write it in §5.1.
In that case, yes, we should say that the order of paragraphs is
significant, since indeed it always has been. Probably just by adding the
sentence "The order of paragraphs in the control file is significant" to
the end of the first paragraph.
> Line escape and paragraph separators
> ------------------------------------
> “Blank lines, or lines consisting only of spaces and tabs, are not
> allowed within field values or between fields”. The Description and
> Changes fields introduce a convention to escape blank lines,
> representing them by a space followed by a dot. How describing this
> convention directly in §5.1?
Sure, that sounds like a good idea.
> Also, while submitting this bug, I found #501930 about paragraph
> separation. If the outcome of this discussion is a patch, I propose to
> let it addres #501930 as well, by adding “lines consisting only of
> spaces and tabs” to the second sentence of §5.1.
I'm torn on that bug. The ideal thing to do there, I think, is to say
that lines consisting solely of spaces and tabs are a syntax error and are
not allowed, but parsers may accept them as paragraph separators. (Be
conservative in what you generate and liberal in what you accept.) I'm
concerned that we have code out there that doesn't recognize them as
paragraph separators, and explicitly allowing them will make that code
buggy.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: