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 ec605c60662682d4ae3e690d40e8a8841b7d0ce9..91173a5d8dc75381d63d02ea5070944ea9e4b513 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -2479,19 +2479,26 @@ endif
          fields<footnote>
                The paragraphs are also sometimes referred to as stanzas.
          </footnote>.
          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.  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
          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
        </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
+         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
          (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
        </p>
 
        <p>
        </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. 
+         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, is 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 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.
+           </item>
+         </taglist>

        </p>
 
        <p>
        </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
+         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>
 
           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.
        <p>
          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
        </p>
 
        <p>
        </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
+         between two continuation lines.  They do not end logical lines.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -2600,8 +2645,8 @@ 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
          <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
-         <file>debian/control</file> but not in any other control
+         archive.  Some fields are folded 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
          <file>debian/control</file> to generate other control files.
          file. These tools are responsible for removing the line
          breaks from such fields when using fields from
          <file>debian/control</file> to generate other control files.


@@ -2614,16 +2659,6 @@ Package: libc6
          when they generate output control files.
          See <ref id="substvars"> for details.
        </p>
          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">
       </sect>
 
       <sect id="binarycontrolfiles">


@@ -2822,11 +2857,7 @@ Package: libc6
          </p>
 
          <p>
          </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>
 
          </p>
        </sect1>
 


@@ -3006,7 +3037,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
          <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>
          </p>
 
          <p>


@@ -3242,7 +3273,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
            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>
          </p>
 
          <p>


@@ -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 <tt>Description:</tt>) is
            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
+           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.
            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.


@@ -3443,7 +3475,7 @@ Package: libc6
          <heading><tt>Changes</tt></heading>
 
          <p>
          <heading><tt>Changes</tt></heading>
 
          <p>

-           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.
          </p>
 
            the differences between the last version and the current one.
          </p>
 


@@ -3481,7 +3513,7 @@ Package: libc6
          <heading><tt>Binary</tt></heading>
 
          <p>
          <heading><tt>Binary</tt></heading>
 
          <p>

-           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.
          </p>
            meaning varies depending on the control file in which it
            appears.
          </p>


@@ -3491,7 +3523,7 @@ Package: libc6
            packages which a source package can produce, separated by
            commas<footnote>
                A space after each comma is conventional.
            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>.  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
            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
          <p>
            When it appears in a <file>.changes</file> file, it lists the
            names of the binary packages being uploaded, separated by
          <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).

          </p>
        </sect1>
 
          </p>
        </sect1>
 


@@ -3624,7 +3656,7 @@ Files:
            and <tt>Checksums-Sha256</tt></heading>
 
          <p>
            and <tt>Checksums-Sha256</tt></heading>
 
          <p>

-           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 <tt>Checksums-Sha1</tt>
            and <tt>Checksums-Sha256</tt> have the same syntax and differ
            only in the checksum algorithm used: SHA-1
            for each one.  Both <tt>Checksums-Sha1</tt>
            and <tt>Checksums-Sha256</tt> 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 <ref
          id="controlsyntax">, and must appear where it's necessary to
          disambiguate; it is not otherwise significant.  All of the
          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
+         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
          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
+         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>
          is conventional to do so after a comma and before the space
          following that comma.
        </p>