Le Thu, Sep 02, 2010 at 06:52:15PM -0700, Russ Allbery a écrit :
>
> The distinction really is that some fields can be folded (Build-*, for
> example) and some fields are multi-line (Description, Files). The
> multi-line fields are not folded in the RFC 5322 sense, since you cannot
> just remove the newlines and have semantically the same content. Those
> fields (Description, Files) are a separate type of field that RFC 5322
> doesn't have.
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 ? Also, I
integrated your comment about the relationships fields, that can not be folded
elsewhere than in source package files.
The attached patch also contains the (corrected) addition of the
DM-Upload-Allowed field.
I wonder if it would be worthwile to add the Bugs and Origin fields as well.
Have a nice Sunday,
--
Charles Plessy
Tsurumi, Kanagawa, Japan
diff --git a/policy.sgml b/policy.sgml
index edd1faf..23fb14b 100644
--- 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
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.
</p>
<p>
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
+ the end of a logical 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
@@ -2479,22 +2482,42 @@ Package: libc6
</p>
<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>
<p>
- 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
+ Continuation lines need to be allowed for each field separately,
+ by specifiying that the field can be folded or that it is multiline.
+ <list compact="compact">
+ <item>
+ In fields that can be folded, whitespace including newlines
+ is not significant in the field values<footnote>
+ This allows simple control files that contain only one paragraph
+ and no multiline field to be read by parsers written for
+ the RFC 2822.</footnote>.
+ </item>
+ <item>
+ In multiline fields, whitespace including newlines is significant.
+ </item>
+ </list>
+ </p>
+
+ <p>
+ 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.
</p>
<p>
+ The presence and purpose of a field, and the syntax of its
+ value may differ between types of control files.
+ </p>
+
+ <p>
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
Field values are case-sensitive unless the description of the
@@ -2502,9 +2525,17 @@ Package: libc6
</p>
<p>
- 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.
+ </p>
+
+ <p>
+ Lines starting with # without any preceding whitespace are comments
+ lines that are only permitted in source package control files
+ (<file>debian/control</file>). These comment lines are ignored, even
+ in the middle of continuation lines. They do not end logical lines.
</p>
<p>
@@ -2535,6 +2566,7 @@ Package: libc6
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
+ <item><qref id="f-DM-Upload-Allowed"<tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
<item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
@@ -2569,7 +2601,7 @@ Package: libc6
<file>.changes</file> file to accompany the upload, and by
<prgn>dpkg-source</prgn> when it creates the
<file>.dsc</file> source control file as part of a source
- archive. Many fields are permitted to span multiple lines in
+ archive. Continuation lines can be permitted for some fields in
<file>debian/control</file> but not in any other control
file. These tools are responsible for removing the line
breaks from such fields when using fields from
@@ -2583,16 +2615,6 @@ Package: libc6
when they generate output control files.
See <ref id="substvars"> for details.
</p>
-
- <p>
- In addition to the control file syntax described <qref
- id="controlsyntax">above</qref>, this file may also contain
- comment lines starting with <tt>#</tt> 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.
- </p>
-
</sect>
<sect id="binarycontrolfiles">
@@ -2640,6 +2662,7 @@ Package: libc6
<item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
+ <item><qref id="f-DM-Upload-Allowed"<tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
@@ -2790,14 +2813,23 @@ Package: libc6
</p>
<p>
- Any parser that interprets the Uploaders field in
- <file>debian/control</file> 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 <file>debian/control</file> can be folded.
</p>
</sect1>
+ <sect1 id="f-DM-Upload-Allowed">
+ <heading><tt>DM-Upload-Allowed</tt></heading>
+
+ <p>
+ The most recent version of a package uploaded to unstable or
+ experimental must include the field "DM-Upload-Allowed: yes" in the
+ source section of its source control file for the Debian archive to
+ accept uploads signed with a key in the Debian Maintainer keyring.
+ See the General Resolution <url id="http://www.debian.org/vote/2007/vote_003";
+ name="Endorse the concept of Debian Maintainers"> for more details.
+ </p>
+ </sect1>
+
<sect1 id="f-Changed-By">
<heading><tt>Changed-By</tt></heading>
@@ -2974,7 +3006,7 @@ Package: libc6
<p>
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.
</p>
<p>
@@ -3210,7 +3242,8 @@ Package: libc6
In a source or binary control file, the <tt>Description</tt>
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:
</p>
<p>
@@ -3274,9 +3307,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 <tt>Description:</tt>) is
- always empty. The content of the field is expressed as
- continuation lines, one line per package. Each line is
- indented by one space and contains the name of a binary
+ 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 (<tt>-</tt>), a space, and the
short description line from that package.
</p>
@@ -3416,8 +3448,8 @@ Package: libc6
</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
field is expressed as continuation lines, with each line
indented by at least one space. Blank lines must be
represented by a line consisting only of a space and a full
@@ -3459,7 +3491,7 @@ Package: libc6
packages which a source package can produce, separated by
commas<footnote>
A space after each comma is conventional.
- </footnote>. It may span multiple lines. The source package
+ </footnote>, and can be folded. 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
@@ -3469,7 +3501,7 @@ Package: libc6
<p>
When it appears in a <file>.changes</file> file, it lists the
names of the binary packages being uploaded, separated by
- whitespace (not commas). It may span multiple lines.
+ whitespace (not commas), and can be folded.
</p>
</sect1>
@@ -3495,14 +3527,13 @@ Package: libc6
<heading><tt>Files</tt></heading>
<p>
- This field contains a list of files with information about
+ This multiline field contains a list of files with information about
each one. The exact information and syntax varies with
the context.
</p>
<p>
- In all cases, Files is a multiline field. The first line of
- the field value (the part on the same line as <tt>Files:</tt>)
+ The first line of the field value (the part on the same line as <tt>Files:</tt>)
is always empty. The content of the field is expressed as
continuation lines, one line per file. Each line must be
indented by one space and contain a number of sub-fields,
@@ -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
<prgn>dpkg</prgn> 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
- is conventional to do so after a comma and before the space
- following that comma.
+ 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.
</p>
<p>
