Bug#593909: debian-policy: Clarifications about the syntax of Debian control files.
Charles Plessy <plessy@debian.org> writes:
> I think that it is an excellent idea to use the vocabulary of the
> RFC. It has been written many times that the control files follow the
> syntax of the RFC 822 and its successors, and I think that it would help
> to show where this is true and where it is not.
> In the attached patch, I refer to the RFC 2822: isn't 5322 a draft ?
There are three stages to the IETF standards process: Proposed Standard,
Draft Standard, and Standard (or "full standard"). Documents can only
advance along this track if there are no substantive changes (with some
specific exceptions), so any major revision reverts back to Proposed and
has to go through those steps.
The only full Standard for the format is RFC 822, but it's widely
considered obsolete. RFC 2822 was the Proposed Standard to replace and
update it, and RFC 5322 is the Draft Standard advancement of RFC 2822.
If one is very conservative, one may still want to refer to RFC 822
instead of the successors since its successors have not yet reached full
standard, but it's always wrong at this point to refer to RFC 2822 in
preference to RFC 5322, since the latter is one step farther down the
acceptance process than the former and has only "bug fixes" relative to
2822.
> The attached patch also contains the (corrected) addition of the
> DM-Upload-Allowed field.
I've since merged this separately, so an updated patch with fixes to the
above and rebased against the current repository would be good. (In
general, please don't combine different issues into one patch. Git should
hopefully make it relatively easy to juggle multiple branches.)
> I wonder if it would be worthwile to add the Bugs and Origin fields as
> well.
I don't think so, since neither should be set for any packages in the
Debian archive. They're more of a dpkg feature intended for non-Debian
packages.
> --- a/policy.sgml
> +++ b/policy.sgml
> @@ -2449,19 +2449,22 @@ endif
> fields<footnote>
> The paragraphs are also sometimes referred to as stanzas.
> </footnote>.
> - The paragraphs are separated by blank lines. Some control
> + The paragraphs are separated by empty lines. As a special exception
> + for backwards compatibility, parsers may accept lines consisting
> + solely of spaces and tabs as paragraph separators. Some control
I don't think it's a big deal, but I'd phrase this sentence as:
Parsers may accept lines consisting solely of spaces and tabs as
paragraph separators, but control files should use empty lines.
I don't think the compatibility is for backward compatibility as much as
because it's easy to do this by accident.
> files allow only one paragraph; others allow several, in
> which case each paragraph usually refers to a different
> package. (For example, in source packages, the first
> paragraph refers to the source package, and later paragraphs
> - refer to binary packages generated from the source.)
> + refer to binary packages generated from the source.). The
I can fix this when applying it, but when the entire sentence is
parenthesized, there should be only one period, placed inside the
parentheses.
> <p>
> - Many 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.
> + Fields values may be contained in a logical line that spans
> + several lines; these lines are called continuation lines and
> + 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.
> </p>
How about this:
<p>
There are three types of fields:
<taglist>
<tag>simple</tag>
<item>
The field, including its value, must be a single line. Folding
of the field is not permitted. This is the default field type
if the definition of the field does not specify a different
type.
</item>
<tag>folded</tag>
<item>
The value of a folded field is a logical line that may span
several lines. The lines after the first are called
continuation lines and must start with a space or a tab.
Whitespace, including any newlines, are not significant in the
field values of folded fields.<footnote>
This folding method is similar to RFC 5322, allowing control
files that contain only one paragraph and no multiline fields
to be read by parsers written for RFC 5322.
</footnote>
</item>
<tag>multiline</tag>
<item>
The value of a multiline field may consist of multiple lines.
The first line of the value, the part on the same line as the
field name, often has special significance or may have to be
empty. Whitespace, including newlines, is significant in the
values of multiline fields.
</item>
</taglist>
</p>
> <p>
> - The first line of the field value (the part on the same line
> - as <tt>Changes:</tt>) is always empty. The content of the
> + The first line of this multiline field (the part on the same
> + line as <tt>Changes:</tt>) is always empty. The content of the
I think you still need to keep the word "value" here.
> @@ -4425,16 +4456,16 @@ Checksums-Sha256:
> Whitespace may appear at any point in the version
> specification subject to the rules in <ref
> id="controlsyntax">, and must appear where it's necessary to
> - disambiguate; it is not otherwise significant. All of the
> - relationship fields may span multiple lines. For
> - consistency and in case of future changes to
> + disambiguate; it is not otherwise significant.
> + The relationship fields can only be folded in source package
> + control files For consistency and in case of future changes to
Missing end of sentence punctuation here.
Otherwise, this looks great to me.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: