From: Charles Plessy
Date: Tue, 12 Oct 2010 15:14:42 +0000 (+0900)
Subject: Clarification of the format of control files, Closes: #501930, #593909.
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=0ecd2cf30502d7e428b3ee6637c1ca5909fdefaa;hp=3635b8fc207b04dee283409c786633669f8c422e;p=debian%2Fdebian-policy.git
Clarification of the format of control files, Closes: #501930, #593909.
- Specifies field names similarly to RFC 822/5832;
- Distinguishes simple, folded and mulitiline fields;
- Clarifies paragraph separators (#501930);
- The order of paragraphs is significant;
- Fields can have different types or purposes in different control files;
- Moved the description of comments from §5.2 to §5.1;
- Documented that relationship fields can only be folded in debian/control.
---
diff --git a/policy.sgml b/policy.sgml
index ec605c6..91173a5 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2479,19 +2479,26 @@ endif
fields
The paragraphs are also sometimes referred to as stanzas.
.
- The paragraphs are separated by blank lines. Some control
+ The paragraphs are separated by empty lines. Parsers may accept
+ lines consisting solely of spaces and tabs as paragraph
+ separators, but control files should use empty lines. Some control
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
+ ordering of the paragraphs in control files is significant.
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 (logical) line. Horizontal whitespace
+ then the data/value associated with that field. The field
+ name is composed of printable ASCII characters (i.e.,
+ characters that have values between 33 and 126, inclusive)
+ except colon and must not with a begin with #. The
+ field ends at the end of the line or at the end of the
+ last continuation line (see below). Horizontal whitespace
(spaces and tabs) may occur immediately before or after the
value and is ignored there; it is conventional to put a
single space after the colon. For example, a field might
@@ -2509,21 +2516,51 @@ Package: libc6
- 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.
+ There are three types of fields:
+
+ simple
+ -
+ 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.
+
+ folded
+ -
+ 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, is not significant in the
+ field values of folded fields.
+ 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.
+
+
+ multiline
+ -
+ The value of a multiline field may comprise multiple continuation
+ 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. Other lines are added following the same syntax as the
+ continuation lines the folded fields. Whitespace, including newlines,
+ is significant in the values of multiline fields.
+
+
- 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
+ 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.
+
+ The presence and purpose of a field, and the syntax of its
+ value may differ between types of control files.
+
+
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
@@ -2532,9 +2569,17 @@ Package: libc6
- Blank lines, or lines consisting only of spaces and tabs,
- are not allowed within field values or between fields - that
- would mean a new paragraph.
+ Paragraph separators (empty lines) and lines consisting only of
+ spaces and tabs are not allowed within field values or between
+ fields. Empty lines in field values are usually escaped by
+ representing them by a space followed by a dot.
+
+
+
+ Lines starting with # without any preceding whitespace are comments
+ lines that are only permitted in source package control files
+ (debian/control). These comment lines are ignored, even
+ between two continuation lines. They do not end logical lines.
@@ -2600,8 +2645,8 @@ Package: libc6
.changes file to accompany the upload, and by
dpkg-source when it creates the
.dsc 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
+ archive. Some fields are folded 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.
@@ -2614,16 +2659,6 @@ Package: libc6
when they generate output control files.
See [ for details.
]
-
-
- In addition to the control file syntax described above, this file may also contain
- comment lines starting with # without any preceding
- whitespace. All such lines are ignored, even in the middle of
- continuation lines for a multiline field, and do not end a
- multiline field.
-
-
@@ -2822,11 +2857,7 @@ Package: libc6
- Any parser that interprets the Uploaders field in
- debian/control must permit it to span multiple
- lines. Line breaks in an Uploaders field that spans multiple
- lines are not significant and the semantics of the field are
- the same as if the line breaks had not been present.
+ The Uploaders field in debian/control can be folded.
@@ -3006,7 +3037,7 @@ Package: libc6
This is a boolean field which may occur only in the
control file of a binary package or in a per-package fields
- paragraph of a main source control data file.
+ paragraph of a source package control file.
@@ -3242,7 +3273,8 @@ Package: libc6
In a source or binary control file, the Description
field contains a description of the binary package, consisting
of two parts, the synopsis or the short description, and the
- long description. The field's format is as follows:
+ long description. It is a multiline field with the following
+ format:
@@ -3306,8 +3338,8 @@ Package: libc6
field contains a summary of the descriptions for the packages
being uploaded. For this case, the first line of the field
value (the part on the same line as Description:) is
- always empty. The content of the field is expressed as
- continuation lines, one line per package. Each line is
+ always empty. It is a multiline field, with one
+ line per package. Each line is
indented by one space and contains the name of a binary
package, a space, a hyphen (-), a space, and the
short description line from that package.
@@ -3443,7 +3475,7 @@ Package: libc6
Changes
- This field contains the human-readable changes data, describing
+ This multiline field contains the human-readable changes data, describing
the differences between the last version and the current one.
@@ -3481,7 +3513,7 @@ Package: libc6
Binary
- This field is a list of binary packages. Its syntax and
+ This folded field is a list of binary packages. Its syntax and
meaning varies depending on the control file in which it
appears.
@@ -3491,7 +3523,7 @@ Package: libc6
packages which a source package can produce, separated by
commas
A space after each comma is conventional.
- . It may span multiple lines. The source package
+ . The source package
does not necessarily produce all of these binary packages for
every architecture. The source control file doesn't contain
details of which architectures are appropriate for which of
@@ -3501,7 +3533,7 @@ Package: libc6
When it appears in a .changes file, it lists the
names of the binary packages being uploaded, separated by
- whitespace (not commas). It may span multiple lines.
+ whitespace (not commas).
@@ -3624,7 +3656,7 @@ Files:
and Checksums-Sha256
- These fields contain a list of files with a checksum and size
+ These multiline fields contain a list of files with a checksum and size
for each one. Both Checksums-Sha1
and Checksums-Sha256 have the same syntax and differ
only in the checksum algorithm used: SHA-1
@@ -4562,13 +4594,13 @@ fi
specification subject to the rules in [, and must appear where it's necessary to
disambiguate; it is not otherwise significant. All of the
- relationship fields may span multiple lines. For
+ relationship fields can only be folded in source package control files. For
consistency and in case of future changes to
dpkg it is recommended that a single space be
used after a version relationship and before a version
number; it is also conventional to put a single space after
each comma, on either side of each vertical bar, and before
- each open parenthesis. When wrapping a relationship field, it
+ each open parenthesis. When opening a continuation line in a relationship field, it
is conventional to do so after a comma and before the space
following that comma.
]